Smartsheet API 2.0

Sample Code (more information here)

# The cURL code samples included in this API documentation demonstrate how to execute operations using the command line data transfer tool cURL: http://en.wikipedia.org/wiki/CURL. 
// The Node.js code samples included in this API documentation demonstrate how to execute operations using the Smartsheet JavaScript SDK: https://github.com/smartsheet-platform/smartsheet-javascript-sdk.
// The C# code samples included in this API documentation demonstrate how to execute operations using the Smartsheet C# SDK: https://github.com/smartsheet-platform/smartsheet-csharp-sdk.
// The Java code samples included in this API documentation demonstrate how to execute operations using the Smartsheet Java SDK: https://github.com/smartsheet-platform/smartsheet-java-sdk.

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:

/contacts
/favorites
/folders
/groups
/home
/reports
/search
/serverinfo
/sheets
/sheets/{id}/rows
/sheets/{id}/columns
/sheets/{id}/attachments
/sheets/{id}/discussions
/sheets/{id}/updateRequests
/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

For every API operation in this documentation, we show example requests in multiple languages and an example (JSON) response. You’ll see the examples displayed in the dark blue panel next to each operation. To view the sample code in a specific language, select the corresponding language tab along the top of the dark blue panel. For more information about using the sample code in this API documentation, see SDKs and Sample Code.

As with any REST API, you can 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}’
1148 Numeric cell values must be between {0} and {1}.
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

Smartsheet SDKs (client libraries) are available in a variety of languages. For the complete list, see our SDK page. Submit your vote for additional language coverage by emailing us at api@smartsheet.com.

This API documentation currently contains sample code in the following languages:

  • cURL
  • C#
  • Java
  • Node.js

For each operation, you’ll see sample code displayed in the dark blue panel next to the operation. To view the sample code in a specific language, select the corresponding language tab along the top of the dark blue panel. Each C#, Java, and Node.js code sample demonstrates how to execute an operation using the corresponding Smartsheet SDK. See the corresponding section below for more information about using the sample code in a specific language.

cURL Sample Code

The cURL code samples included in this API documentation demonstrate how to execute operations using the command line data transfer tool cURL.

C# Sample Code

The C# code samples included in this API documentation demonstrate how to execute operations using the Smartsheet C# SDK. To use the C# SDK, you’ll need to include the appropriate using directives in your code. For example:

using Smartsheet.Api;
using Smartsheet.Api.Models;
using Smartsheet.Api.OAuth;

Each code sample uses a SmartsheetClient object called “smartsheet” that can be created as follows:

// Set the Access Token
Token token = new Token();
token.AccessToken = "INSERT_YOUR_TOKEN_HERE";

// Use the Smartsheet Builder to create a Smartsheet
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).Build();

For operations that support querystring parameters, the C# code sample often contains multiple example requests, each one showing a different combination of querystring parameters. The code samples are intended for example purposes only and should not be considered to cover all possible combinations of querystring parameters.

Within the C# code samples, the …Id naming convention is used to denote an object ID that will need to be replaced with an actual object ID, should you use the code in your application. For example, in the following code example, sheetId should be replaced with the actual ID of the Sheet and rowId should be replaced with the actual ID of the Row:

smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussion(sheetId, rowId, discussion);

Java Sample Code

The Java code samples included in this API documentation demonstrate how to execute operations using the Smartsheet Java SDK. To use the Java SDK, you’ll need to include the appropriate import directives in your code. For example:

import com.smartsheet.api.*;
import com.smartsheet.api.models.*;
import com.smartsheet.api.models.enums.*;
import com.smartsheet.api.oauth.*;

Each code sample uses a Smartsheet object called “smartsheet” that can be created as follows:

// Set the Access Token
Token token = new Token();
token.setAccessToken("INSERT_YOUR_TOKEN_HERE");

// Use the Smartsheet Builder to create a Smartsheet
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(token.getAccessToken()).build();

For operations that support querystring parameters, the Java code sample often contains multiple example requests, each one showing a different combination of querystring parameters. The code samples are intended for example purposes only and should not be considered to cover all possible combinations of querystring parameters.

Within the Java code samples, the …Id naming convention is used to denote an object ID that will need to be replaced with an actual object ID, should you use the code in your application. For example, in the following code example, sheetId should be replaced with the actual ID of the Sheet and rowId should be replaced with the actual ID of the Row:

smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(sheetId, rowId, discussion);

Node.js Sample Code

The Node.js code samples included in this API documentation demonstrate how to execute operations using the Smartsheet JavaScript SDK, with promises. Each code sample uses a root module called “smartsheet” that can be created as follows:

var client = require('smartsheet');
var smartsheet = client.createClient({accessToken:'INSERT_YOUR_TOKEN_HERE'});

Once you’ve created the smartsheet variable, you can use it to execute API operations. For example, the following code example shows how to execute the Get Current User operation.

smartsheet.users.getCurrentUser()
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

For more information about using the Smartsheet JavaScript SDK, including examples of using callbacks (instead of promises), see the SDK Readme.

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"
// Set the access token.
var client = require('smartsheet');
var smartsheet = client.createClient({accessToken:'INSERT_YOUR_TOKEN_HERE'});

// Get current user.
smartsheet.users.getCurrentUser()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Set the access token.
Token token = new Token();
token.AccessToken = "INSERT_YOUR_TOKEN_HERE";
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).Build();

// Get current user.
smartsheet.UserResources.GetCurrentUser();
// Set the access token.
Token token = new Token();
token.setAccessToken("INSERT_YOUR_TOKEN_HERE");
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(token.getAccessToken()).build();

// Get current user.
smartsheet.userResources().getCurrentUser();

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
READ_CONTACTS Retrieve contacts
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://app.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://app.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(app_secret|code)}' \
-X POST
// [todo]
// [todo]
// [todo]

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 App secret concatenated with a pipe and the authorization code. The app_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 App 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(app_secret|refresh_token)}' \
-X POST
// [todo]
// [todo]
// [todo]

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 App 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

Example Request:

curl https://api.smartsheet.com/2.0/users/me \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Assume-User: john.doe%40smartsheet.com" 
// [todo]
// Create the 'smartsheet' object and set the 'Assume-User' header value to "john.doe@smartsheet.com".
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).SetAssumedUser("john.doe@smartsheet.com").Build();

// Get current user (call gets executed as "john.doe@smartsheet.com").
UserProfile userProfile = smartsheet.UserResources.GetCurrentUser();
// Create the 'smartsheet' object and set the 'Assume-User' header value to "john.doe@smartsheet.com".
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(accessToken).setAssumedUser("john.doe@smartsheet.com").build();

// Get current user (call gets executed as "john.doe@smartsheet.com").
UserProfile user= smartsheet.userResources().getCurrentUser();

Example Response:

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

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}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Assume-User: john.doe%40smartsheet.com" \
-H "Content-Type: application/json" \
-X POST \
-d '{"text":"This is a new comment."}'
// [todo]
// Create the 'smartsheet' object and set the 'Assume-User' header value to "john.doe@smartsheet.com".
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).SetAssumedUser("john.doe@smartsheet.com").Build();

// Create comment.
Comment comment = new Comment.AddCommentBuilder("This is a new comment.").Build();

// Add comment to discussion (call gets executed as "john.doe@smartsheet.com").
smartsheet.SheetResources.DiscussionResources.CommentResources.AddComment(sheetId, discussionId, comment);
// Create the 'smartsheet' object and set the 'Assume-User' header value to "john.doe@smartsheet.com".
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(accessToken).setAssumedUser("john.doe@smartsheet.com").build();

// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This is a new comment.").build();

// Add comment to discussion (call gets executed as "john.doe@smartsheet.com").
smartsheet.sheetResources().discussionResources().commentResources().addComment(sheetId, discussionId, 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
}

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"
smartsheet.sheets.listOrganizationSheets()
    .then(function(data) {
        console.log(data)
    })
    .catch(function(error) {
        console.log(error);
    });
// List all org sheets.
smartsheet.UserResources.SheetResources.ListSheets();
// List all org sheets.
smartsheet.userResources().listOrgSheets();

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"
// [todo]
// [todo]
// [todo]

Fetch each attachment:

curl -0 URL_TO_ATTACHMENT
// [todo]
// [todo]
// [todo]

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 Change Log

This section documents the evolution of Smartsheet API 2.0 over time. To stay informed about changes to the API, we recommend that you periodically review this list for new information, subscribe to our Developer Newsletter (using the Get Developer Updates form on the Smartsheet Developer Portal) or follow us via Twitter.

August 14, 2015

Backwards-compatible updates to Smartsheet API 2.0.

  • New endpoints for accessing Contacts, copy/move Folder/Sheet, copy Workspace, bulk Row delete, bulk Send Rows, Send Update Request.

  • API enhancements that enable you to attach a link to a file in Egnyte, lock and unlock Rows/Columns, get more information about Sheets/Reports/Users, choose Columns to include when sending Rows via email, send a Gantt view of a Sheet via email (in PDF format), create Discussion on Row using a multipart upload, include everything when copying a Row from one sheet to another, and retrieve a permalink for a Row.

  • New access scope for retrieving Contacts.

  • Deprecations: Delete (single) Row endpoint, Send (single) Row endpoint, fromId attribute and include parameter on the Create Sheet/Folder/Workspace endpoints.

  • Bug fixes: Add Column(s) operation now returns correct Ids for new columns; Revoke Token operation no longer returns error code 1004 “not authorized”.

For more detailed information about this release, see the release notes.

July 11, 2015

Initial release of Smartsheet API 2.0. For detailed information about API 2.0 features and guidance for migrating from API 1.1 to API 2.0, see the release notes.

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, EVERNOTE, or EGNYTE)
attachmentSubType string Attachment sub type, valid only for either GOOGLE_DRIVE attachments or EGNYTE attachments:
  • possible values for GOOGLE_DRIVE attachments: DOCUMENT, SPREADSHEET, PRESENTATION, PDF, DRAWING
  • possible values for EGNYTE attachments: FOLDER
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"
// n/a
// Attach file to comment.
smartsheet.SheetResources.CommentResources.AttachmentResources.AttachFile(sheetId, commentId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to comment.
smartsheet.sheetResources().commentResources().attachmentResources().attachFile(sheetId, commentId, file, "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
// Set options.
var options = {
    contentType: CONTENT_TYPE,
    fileName: NAME_OF_FILE,
    fileSize: SIZE_OF_FILE,
    body: ATTACHMENT_DATA,
    sheetId: 2252168947361668,
    commentId: 4293147074291588
};

// Attach file to comment.
smartsheet.sheets.addCommentAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// Attach file to comment.
smartsheet.SheetResources.CommentResources.AttachmentResources.AttachFile(sheetId, commentId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to comment.
smartsheet.sheetResources().commentResources().attachmentResources().attachFile(sheetId, commentId, file, "application/msword");

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"
// n/a
// Attach file to row.
smartsheet.SheetResources.RowResources.AttachmentResources.AttachFile(sheetId, rowId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to row.
smartsheet.sheetResources().rowResources().attachmentResources().attachFile(sheetId, rowId, file, "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
// Set options.
var options = {
    contentType: CONTENT_TYPE,
    fileName: NAME_OF_FILE,
    fileSize: SIZE_OF_FILE,
    body: ATTACHMENT_DATA,
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Attach file to row.
smartsheet.sheets.addRowAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// Attach file to row.
smartsheet.SheetResources.RowResources.AttachmentResources.AttachFile(sheetId, rowId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to row.
smartsheet.sheetResources().rowResources().attachmentResources().attachFile(sheetId, rowId, file, "application/msword");

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"
// n/a
// Attach file to sheet.
smartsheet.SheetResources.AttachmentResources.AttachFile(sheetId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to sheet.
smartsheet.sheetResources().attachmentResources().attachFile(sheetId, file, "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
// Set options.
var options = {
    contentType: CONTENT_TYPE,
    fileName: NAME_OF_FILE,
    fileSize: SIZE_OF_FILE,
    body: ATTACHMENT_DATA,
    sheetId: 2252168947361668
};

// Attach file to sheet.
smartsheet.sheets.addAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// Attach file to sheet.
smartsheet.SheetResources.AttachmentResources.AttachFile(sheetId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to sheet.
smartsheet.sheetResources().attachmentResources().attachFile(sheetId, file, "application/msword");

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"}'
// Specify URL attachment.
var attachment = {
    "name": "Search Engine",
    "attachmentType": "LINK",
    "url": "http://www.google.com"
};

// Set options.
var options = {
    body: attachment,
    sheetId: 2252168947361668,
    commentId: 4445024629876612
};

// Attach URL to comment.
smartsheet.sheets.addCommentAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder("http://www.google.com", AttachmentType.LINK).SetName("Search Engine").SetDescription("A popular search engine").Build();

// Attach URL to comment.
smartsheet.SheetResources.CommentResources.AttachmentResources.AttachUrl(sheetId, commentId, attachment);
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder().setUrl("http://www.google.com").setAttachmentType(AttachmentType.LINK).setName("Search Engine").setDescription("A popular search engine").build();

// Attach URL to comment.
smartsheet.sheetResources().commentResources().attachmentResources().attachUrl(sheetId, commentId, attachment);

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”)
  • an Egnyte URL (attachmentType “EGNYTE”)

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"}'
// Specify URL attachment.
var attachment = {
    "name": "Search Engine",
    "description": "A popular search engine",
    "attachmentType": "LINK",
    "url": "http://www.google.com"
};

// Set options.
var options = {
    body: attachment,
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Attach URL to row.
smartsheet.sheets.addRowAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder("http://www.google.com", AttachmentType.LINK).SetName("Search Engine").SetDescription("A popular search engine").Build();

// Attach URL to row.
smartsheet.SheetResources.RowResources.AttachmentResources.AttachUrl(sheetId, rowId, attachment);
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder().setUrl("http://www.google.com").setAttachmentType(AttachmentType.LINK).setName("Search Engine").setDescription("A popular search engine").build();

// Attach URL to row.
smartsheet.sheetResources().rowResources().attachmentResources().attachUrl(sheetId, rowId, attachment);

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”)
  • an Egnyte URL (attachmentType “EGNYTE”)

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"}'
// Specify URL attachment.
var attachment = {
    "name": "Search Engine",
    "description": "A popular search engine",
    "attachmentType": "LINK",
    "url": "http://www.google.com"
};

// Set options.
var options = {
    body: attachment,
    sheetId: 2252168947361668
};

// Attach URL to sheet.
smartsheet.sheets.addAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder("http://www.google.com", AttachmentType.LINK).SetName("Search Engine").SetDescription("A popular search engine").Build();

// Attach URL to sheet.
smartsheet.SheetResources.AttachmentResources.AttachUrl(sheetId, attachment);
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder().setUrl("http://www.google.com").setAttachmentType(AttachmentType.LINK).setName("Search Engine").setDescription("A popular search engine").build();

// Attach URL to sheet.
smartsheet.sheetResources().attachmentResources().attachUrl(sheetId, attachment);

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”)
  • an Egnyte URL (attachmentType “EGNYTE”)

Delete Attachment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    sheetId: 2252168947361668,
    attachmentId: 7169782752536452,
};

// Delete attachment.
smartsheet.sheets.deleteAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete attachment.
smartsheet.SheetResources.AttachmentResources.DeleteAttachment(sheetId, attachmentId);
// Delete attachment.
smartsheet.sheetResources().attachmentResources().deleteAttachment(sheetId, sheetAttachmentId);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    attachmentId: 4583173393803140
};

// Get attachment.
smartsheet.sheets.getAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get attachment.
smartsheet.SheetResources.AttachmentResources.GetAttachment(sheetId, attachmentId);
// Get attachment.
smartsheet.sheetResources().attachmentResources().getAttachment(sheetId, attachmentId);

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"
// Set options.
var options = {
    sheetId: 2252168947361668
};

// Get all attachments.
smartsheet.sheets.listAttachments(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get all attachments (omit pagination parameters).
smartsheet.SheetResources.AttachmentResources.ListAttachments(sheetId, null);

// Get all attachments (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.AttachmentResources.ListAttachments(sheetId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all attachments with pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().listAttachments(sheetId, parameters);

// Get all attachments without pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().listAttachments(sheetId, null);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    discussionId: 3962273862576004
};

// Get discussion attachments.
smartsheet.sheets.listDiscussionAttachments(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get discussion attachments (omit pagination parameters).
smartsheet.SheetResources.DiscussionResources.AttachmentResources.ListAttachments(sheetId, discussionId, null);

// Get discussion attachments (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.DiscussionResources.AttachmentResources.ListAttachments(sheetId, discussionId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all discussion attachments with pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().discussionResources().attachmentResources().getAttachments(sheetId, discussionId, parameters);

// Get all discussion attachments without pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().discussionResources().attachmentResources().getAttachments(sheetId, discussionId, null);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Get row attachments.
smartsheet.sheets.getRowAttachments(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get row attachments (omit pagination parameters).
smartsheet.SheetResources.RowResources.AttachmentResources.ListAttachments(sheetId, rowId, null);

// Get row attachments (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.RowResources.AttachmentResources.ListAttachments(sheetId, rowId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all row attachments with pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().rowResources().attachmentResources().getAttachments(sheetId, rowId, parameters);

// Get all row attachments without pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().rowResources().attachmentResources().getAttachments(sheetId, rowId, null);

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"
// n/a
// Attach new version of file.
smartsheet.SheetResources.AttachmentResources.VersioningResources.AttachNewVersion(sheetId, attachmentId, filePath, "application/msword");
// Specify the new file to be attached.
File file = new File(filePath);

// Attach new version of the file.
smartsheet.sheetResources().attachmentResources().versioningResources().attachNewVersion(sheetId, attachmentId, file, "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
// Set options.
var options = {
    contentType: CONTENT_TYPE,
    fileName: NAME_OF_FILE,
    fileSize: SIZE_OF_FILE,
    body: ATTACHMENT_DATA,
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Attach new version of the file.
smartsheet.sheets.attachNewVersion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// Attach new version of file.
smartsheet.SheetResources.AttachmentResources.VersioningResources.AttachNewVersion(sheetId, attachmentId, filePath, "application/msword");
// Specify the new file to be attached.
File file = new File(filePath);

// Attach new version of the file.
smartsheet.sheetResources().attachmentResources().versioningResources().attachNewVersion(sheetId, attachmentId, file, "application/msword");

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
// Set options.
var options = {
    sheetId: 2252168947361668,
    attachmentId: 5510069950408580
};

// Delete all versions of the attachment.
smartsheet.sheets.deleteAllAttachmentVersions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete all versions of the attachment. 
smartsheet.SheetResources.AttachmentResources.VersioningResources.DeleteAllVersions(sheetId, attachmentId);
// Delete all versions of the attachment.
smartsheet.sheetResources().attachmentResources().versioningResources().deleteAllVersions(sheetId, attachmentId);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    attachmentId: 5510069950408580
};

// List all versions of the attachment.
smartsheet.sheets.listAttachmentVersions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List all versions of the attachment (omit pagination parameters).
smartsheet.SheetResources.AttachmentResources.VersioningResources.ListVersions(sheetId, attachmentId, null);

// List all versions of the attachment (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.AttachmentResources.VersioningResources.ListVersions(sheetId, attachmentId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List all attachment versions with pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().versioningResources().listAllVersions(sheetId, attachmentId, parameters);

// List all attachment versions without pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().versioningResources().listAllVersions(sheetId, attachmentId, null);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    rowId: 4293147074291588,
    columnId: 642523719853956
};

// Get cell history.
smartsheet.sheets.getCellHistory(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get cell history (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(sheetId, rowId, columnId, null, null);

// Get cell history (specify 'include' parameter with value of "columnType" and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(sheetId, rowId, columnId, new CellInclusion[] { CellInclusion.COLUMN_TYPE }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get cell history with pagination.
PagedResult<CellHistory> cellHistory = smartsheet.sheetResources().rowResources().cellResources().getCellHistory(sheetId, rowId, columnId, parameters);

// Get cell history without pagination.
PagedResult<CellHistory> cellHistory = smartsheet.sheetResources().rowResources().cellResources().getCellHistory(sheetId, rowId, columnId, null);

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. Each element in the array will be set to one of the following values:
  • 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.
locked boolean Flag indicating whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin.
lockedForUser boolean Flag indicating whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.

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":4}, {"title": "New Picklist Column 2", "type": "PICKLIST", "options": ["1", "2", "3"], "index": 4}]'
// Specify new columns.
var column = [
    {
        "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
    }
];

// Set options.
var options = {
    body: column,
    sheetId: 2252168947361668
};

// Add columns to the sheet.
smartsheet.sheets.addColumn(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create a column.
Column columnA = new Column.AddColumnBuilder("New Picklist Column 1", 4, ColumnType.PICKLIST).SetOptions(new string[] { "First", "Second", "Third" }).Build();

// Create another column.
Column columnB = new Column.AddColumnBuilder("New Date Column", 4, ColumnType.DATE).Build();

// Create a third column.
Column columnC = new Column.AddColumnBuilder("New Picklist Column 2", 4, ColumnType.PICKLIST).SetOptions(new string[] { "1", "2", "3" }).Build();

// Add columns to the sheet.
smartsheet.SheetResources.ColumnResources.AddColumns(sheetId, new Column[] { columnA, columnB, columnC });
// Create columns.
Column column1 = new Column.AddColumnToSheetBuilder().setTitle("New Picklist Column 1").setType(ColumnType.PICKLIST).setIndex(4).setOptions(Arrays.asList("First", "Second", "Third")).build();

Column column2 = new Column.AddColumnToSheetBuilder().setTitle("New Date Column").setType(ColumnType.DATE).setIndex(4).build();

Column column3 = new Column.AddColumnToSheetBuilder().setTitle("New Picklist Column 2").setType(ColumnType.PICKLIST).setIndex(4).setOptions(Arrays.asList("1", "2", "3")).build();

// Add columns to the sheet.
smartsheet.sheetResources().columnResources().addColumns(sheetId(), Arrays.asList(column1, column2, column3));

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": 4,
            "title": "New Date Column",
            "type": "DATE",
            "width": 150
        },
        {
            "id": 6755394238748795,
            "index": 4,
            "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)
  • locked (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
// Set options.
var options = {
    sheetId: 2252168947361668,
    columnId: 7881817631025028
};

// Delete column.
smartsheet.sheets.deleteColumn(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete column.
smartsheet.SheetResources.ColumnResources.DeleteColumn(sheetId, columnId);
// Delete column.
smartsheet.sheetResources().columnResources().deleteColumn(sheetId, columnId);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    columnId: 7960873114331012
};

// Get column.
smartsheet.sheets.getColumns(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get column (omit 'include' parameter).
smartsheet.SheetResources.ColumnResources.GetColumn(sheetId, columnId, null);

// Get column (specify 'include' parameter with value of "filters").
smartsheet.SheetResources.ColumnResources.GetColumn(sheetId, columnId, new ColumnInclusion[] { ColumnInclusion.FILTERS });
// Get column (omit 'include' parameter).
smartsheet.sheetResources().columnResources().getColumn(sheetId, columnId, null);

// Get column (specify 'include' parameter with value of "filters").
smartsheet.sheetResources().columnResources().getColumn(sheetId, columnId, EnumSet.of(ColumnInclusion.FILTERS));

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"
// Set options.
var options = {
    sheetId: 2252168947361668
};

// Get all columns.
smartsheet.sheets.getColumns(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get all columns (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.ColumnResources.ListColumns(sheetId, null, null);

// Get all columns (specify 'include' parameter with value of "filters" and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.ColumnResources.ListColumns(sheetId, new ColumnInclusion[] { ColumnInclusion.FILTERS }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all columns (specify 'include' parameter with value of "filters" and 'includeAll' parameter with value of "true").
smartsheet.sheetResources().columnResources().listColumns(sheetId, EnumSet.of(ColumnInclusion.FILTERS), parameters);

// Get all columns (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().columnResources().listColumns(sheetId, null, null);

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"]}'
// Specify column properties.
var column = {
    "index": 0,
    "title": "First Column",
    "type": "PICKLIST",
    "options": ["One", "Two"]
};

// Set options.
var options = {
    body: column,
    sheetId: 2252168947361668,
    columnId: 5005385858869124
};

// Update column.
smartsheet.sheets.updateColumn(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify column properties.
Column column = new Column.UpdateColumnBuilder(columnId, "First Column", 0).SetType(ColumnType.PICKLIST).SetOptions(new string[] { "One", "Two" }).Build();

// Update column.
smartsheet.SheetResources.ColumnResources.UpdateColumn(sheetId, column);
// Specify column properties.
Column column = new Column.UpdateColumnBuilder().setColumnId(columnId).setTitle("First Column").setIndex(0).setType(ColumnType.PICKLIST).setOptions(Arrays.asList("One", "Two")).build();

// Update column.
smartsheet.sheetResources().columnResources().updateColumn(sheetId, column);

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)
    • locked (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."}'
// Specify comment.
var comment = { "text": "This is a new comment." };

// Set options.
var options = {
    body: comment,
    sheetId: 2252168947361668,
    discussionId: 3962273862576004
};

// Add comment to discussion.
smartsheet.sheets.addDiscussionComment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This is a new comment.").Build();

// Add comment to discussion.
smartsheet.SheetResources.DiscussionResources.CommentResources.AddComment(sheetId, discussionId, comment);
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This is a new comment.").build();

// Add comment to discussion.
smartsheet.sheetResources().discussionResources().commentResources().addComment(sheetId, discussionId, 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"
    }
// [todo]
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This is a new comment.").Build();

// Add comment (with attachment) to discussion.
smartsheet.SheetResources.DiscussionResources.CommentResources.AddCommentWithAttachment(sheetId, discussionId, comment, filePath, "application/octet-stream");
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This is a new comment.").build();

// Add comment (with attachment) to discussion.
File file = new File(filePath);

smartsheet.sheetResources().discussionResources().commentResources().addCommentWithAttachment(sheetId, discussionId, comment, file, "application/octet-stream");

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'
// Set options.
var options = {
    sheetId: 2252168947361668,
    commentId: 4952999001909124
};

// Delete comment.
smartsheet.sheets.deleteComment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete comment.
smartsheet.SheetResources.CommentResources.DeleteComment(sheetId, commentId);
// Delete comment.
smartsheet.sheetResources().commentResources().deleteComment(sheetId, commentId);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    commentId: 48569348493401200
};

// Get comment.
smartsheet.sheets.getComment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get comment.
smartsheet.SheetResources.CommentResources.GetComment(sheetId, commentId);
// Get comment.
smartsheet.sheetResources().commentResources().getComment(sheetId, commentId);

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.

Contacts

A Contact is a user’s personal contact in Smartsheet (as described here).

Objects

Contact Object

id string Contact ID
name string Contact’s full name
email string Contact’s email address

Get Contact

Example Request:

curl https://api.smartsheet.com/2.0/contacts/{contactId} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Get contact.
smartsheet.ContactResources.GetContact(contactId);
// Get contact.
smartsheet.contactResources().getContact(contactId);

Example Response:

{
    "id": "AAAAATYU54QAD7_fNhTnhA",
    "name": "David Davidson",
    "email": "dd@example.com"
}

GET /contacts/{contactId}

Gets the specified Contact.

Access Scope READ_CONTACTS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Contact object

List Contacts

Example Request:

curl https://api.smartsheet.com/2.0/contacts \
-H "Authorization: Bearer ACCESS_TOKEN"
// List contacts (omit pagination parameters).
smartsheet.ContactResources.ListContacts(null);

// List contacts (specify 'includeAll' parameter with value of "true").
smartsheet.ContactResources.ListContacts(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List contacts (specify 'includeAll' parameter with value of "true").
smartsheet.contactResources().listContacts(parameters);

// List contacts (omit pagination parameters).
smartsheet.contactResources().listContacts(null);

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": "AAAAATYU54QAD7_fNhTnhA",
            "name": "David Davidson",
            "email": "dd@example.com"
        },
        {
            "id": "AAAAATYU54QAH7_fNhTnhA",
            "name": "Ed Edwin",
            "email": "ee@example.com"
        }
    ]
}

GET /contacts

Gets a list of the user’s Smartsheet Contacts.

Access Scope READ_CONTACTS
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 Contact objects

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 (without attachment):

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"}}'
// Specify discussion.
var discussion = {
    "title": "This is a new discussion",
    "comment": {
        "text": "This text is the body of the first comment"
    }
};

// Set options.
var options = {
    body: discussion,
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Add discussion to row.
smartsheet.sheets.createRowDiscussion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This text is the body of the first comment").Build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder("This is a new discussion", comment).Build();

// Add discussion to row.
smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussion(sheetId, rowId, discussion);
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This text is the body of the first comment").build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder().setTitle("This is a new discussion").setComment(comment).build();

// Add discussion to row.
smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(sheetId, rowId, discussion);

Example Request (with attachment):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-F "discussion=<discussion.json;type=application/json" \
-F "file=@datafile;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"
        }
    }
// [todo]
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This text is the body of the first comment").Build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder("This is a new discussion", comment).Build();

// Add discussion to row.
smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussionWithAttachment(sheetId, rowId, discussion, filePath, "application/octet-stream");
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This text is the body of the first comment").build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder().setTitle("This is a new discussion").setComment(comment).build();

// Set file path
File file = new File(filePath);

// Add discussion to row.
smartsheet.sheetResources().rowResources().discussionResources().createDiscussionWithAttachment(sheetId, rowId, discussion, file, "application/octet-stream");

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "comments": [
            {
                "createdAt": "2013-02-28T22:00:56-08:00",
                "createdBy": {
                    "email": "jane.doe@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.


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.

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"}}'
// Specify discussion.
var discussion = {
    "title": "This is a new discussion",
    "comment": {
        "text": "This text is the body of the first comment"
    }
};

// Set options.
var options = {
    body: discussion,
    sheetId: 2252168947361668
};

// Add discussion to sheet.
smartsheet.sheets.createDiscussion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This text is the body of the first comment").Build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder("This is a new discussion", comment).Build();

// Add discussion to sheet.
smartsheet.SheetResources.DiscussionResources.CreateDiscussion(sheetId, discussion);
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This text is the body of the first comment").build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder().setTitle("This is a new discussion").setComment(comment).build();

// Add discussion to sheet.
smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(sheetId, rowId, discussion);

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"
        }
    }
// [todo]
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This text is the body of the first comment").Build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder("This is a new discussion with an attachment", comment).Build();

// Add discussion (including comment with attachment) to sheet.
smartsheet.SheetResources.DiscussionResources.CreateDiscussionWithAttachment(sheetId, discussion, filePath, "application/octet-stream");
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This text is the body of the first comment").build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder().setTitle("This is a new discussion").setComment(comment).build();
File file = new File(filePath);

// Add discussion (including comment with attachment) to sheet.
smartsheet.sheetResources().discussionResources().createDiscussionWithAttachment(sheetId, discussion, file, "application/octet-stream");

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "comments": [
            {
                "createdAt": "2013-02-28T22:00:56-08:00",
                "createdBy": {
                    "email": "jane.doe@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'
// Set options.
var options = {
    sheetId: 2252168947361668,
    discussionId: 991393444325252
};

// Delete discussion.
smartsheet.sheets.deleteDiscussion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete discussion.
smartsheet.SheetResources.DiscussionResources.DeleteDiscussion(sheetId, discussionId);
// Delete discussion.
smartsheet.sheetResources().discussionResources().deleteDiscussion(sheetId, discussionId);

Example Response:

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

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"
// Set options.
var options = {
    sheetId: 3138415114905476
};

// Get all discussions.
smartsheet.sheets.getDiscussions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get all discussions (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.DiscussionResources.ListDiscussions(sheetId, null, null);

// Get all discussions (specify 'include' parameter with values of 'comments' and 'attachments', and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.DiscussionResources.ListDiscussions(sheetId, new DiscussionInclusion[] { DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all discussions (specify 'include' parameter with values of 'comments' and 'attachments', and 'includeAll' parameter with value of "true").
smartsheet.sheetResources().discussionResources().listDiscussions(sheetId, parameters, EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS));

// Get all discussions (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().discussionResources().listDiscussions(sheetId, null, null);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    discussionId: 2331373580117892
};

// Get discussion.
smartsheet.sheets.getDiscussions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get discussion.
smartsheet.SheetResources.DiscussionResources.GetDiscussion(sheetId, discussionId);
// Get discussion.
smartsheet.sheetResources().discussionResources().getDiscussion(sheetId, discussionId);

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"
// Set options.
var options = {
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Get row discussions.
smartsheet.sheets.getRowDiscussions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get row discussions (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(sheetId, rowId, null, null);

// Get row discussions (specify 'include' parameter with values of 'comments' and 'attachments', and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(sheetId, rowId, new DiscussionInclusion[] { DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get row discussions (specify 'include' parameter with values of 'comments' and 'attachments', and 'includeAll' parameter with value of "true").
smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(sheetId, rowId, parameters, EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS));

// Get row discussions (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(sheetId, rowId, null, null);

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}]'
// Specify favorite(s).
var favorites = [
    {
        "type": "sheet",
        "objectId": 8400677765441412
    }
];

// Set options.
var options = {
    body: favorites
};

// Add item(s) to favorites.
smartsheet.favorites.addItemsToFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify favorite(s).
Favorite[] favorites = new Favorite[] { new Favorite.AddFavoriteBuilder(ObjectType.SHEET, objectId).Build() };

// Add item(s) to favorites.
smartsheet.FavoriteResources.AddFavorites(favorites);
// Specify favorite(s).
List<Favorite> favorites = new Favorite.AddFavoriteBuilder().addFavorite(sheetId, FavoriteType.SHEET).build();

// Add item(s) to favorites.
smartsheet.favoriteResources().addFavorites(favorites);

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"
// List favorites.
smartsheet.favorites.listFavorites()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List favorites (omit pagination parameters).
smartsheet.FavoriteResources.ListFavorites(null);

// List favorites (specify 'includeAll' parameter with value of "true").
smartsheet.FavoriteResources.ListFavorites(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List favorites (specify 'includeAll' parameter with value of "true").
smartsheet.favoriteResources().listFavorites(parameters);

// List favorites (omit pagination parameters).
smartsheet.favoriteResources().listFavorites(null);

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
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove folder from list of favorites.
smartsheet.favorites.removeFolderFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove folder from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.FOLDER, new long[] { folderId });
// Remove folder from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.FOLDER, new HashSet(Arrays.asList(folderId)));

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
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove report from list of favorites.
smartsheet.favorites.removeReportFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove report from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.REPORT, new long[] { reportId });
// Remove report from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.REPORT, new HashSet(Arrays.asList(reportId)));

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
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove sheet from list of favorites.
smartsheet.favorites.removeSheetFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    }); 
// Remove sheet from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.SHEET, new long[] { sheetId });
// Remove sheet from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.SHEET, new HashSet(Arrays.asList(sheetId)));

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 Template

Example Request:

curl https://api.smartsheet.com/2.0/favorites/template/{templateId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove template from list of favorites.
smartsheet.favorites.removeTemplateFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove template from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.TEMPLATE, new long[] { templateId });
// Remove template from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.TEMPLATE, new HashSet(Arrays.asList(templateId)));

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 Favorite Workspace

Example Request:

curl https://api.smartsheet.com/2.0/favorites/workspace/{workspaceId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove workspace from list of favorites.
smartsheet.favorites.removeWorkspaceFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove workspace from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.WORKSPACE, new long[] { workspaceId });
// Remove workspace from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.WORKSPACE, new HashSet(Arrays.asList(workspaceId)));

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 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
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove folders from list of favorites.
smartsheet.favorites.removeFoldersFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove folders from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.FOLDER, new long[] { folderId, folderId2 });
// Remove folders from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.FOLDER, new HashSet(Arrays.asList(folderId1, folderId2)));

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
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove reports from list of favorites.
smartsheet.favorites.removeReportsFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove reports from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.REPORT, new long[] { reportId1, reportId2 });
// Remove reports from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.REPORT, new HashSet(Arrays.asList(reportId1, reportId2)));

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
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove sheets from list of favorites.
smartsheet.favorites.removeSheetsFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove sheets from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.SHEET, new long[] { sheetId1, sheetId2 });
// Remove sheets from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.SHEET, new HashSet(Arrays.asList(sheetId1, sheetId2)));

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
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove templates from list of favorites.
smartsheet.favorites.removeTemplatesFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove templates from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.TEMPLATE, new long[] { templateId1, templateId2 });
// Remove templates from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.TEMPLATE, new HashSet(Arrays.asList(templateId1, templateId2)));

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
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove workspaces from list of favorites.
smartsheet.favorites.removeWorkspacesFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove workspaces from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.WORKSPACE, new long[] { workspaceId1, workspaceId2 });
// Remove workspaces from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.WORKSPACE, new HashSet(Arrays.asList(workspaceId1, workspaceId2)));

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 URL that represents a direct link to the Folder in Smartsheet
sheets Sheet[] Array of Sheet objects
folders Folder[] Array of Folder objects
reports Report[] Array of Report objects
templates Template[] Array of Template objects

Copy Folder

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId}/copy?include=all \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ \
    "destinationType": "workspace|folder|home", \
    "destinationId": workspace_or_folder_id, \
    "newName": "newFolderName" \
}' \
-X POST
// Specify destination.
ContainerDestination destination = new ContainerDestination
{
    DestinationId = destinationFolderId,
    DestinationType = DestinationType.FOLDER,
    NewName = "newFolderName"
};

// Copy folder (omit 'include' and 'skipRemap' parameters).
smartsheet.FolderResources.CopyFolder(folderId, destination, null, null);

// Copy folder (specify 'include' parameter with value of "all", and 'skipRemap' parameter with value of "cellLinks").
smartsheet.FolderResources.CopyFolder(folderId, destination, new FolderCopyInclusion[] { FolderCopyInclusion.ALL }, new FolderRemapExclusion[] { FolderRemapExclusion.CELL_LINKS });
// Specify destination.
ContainerDestination destination = new ContainerDestination.AddContainerDestinationBuilder()
        .setDestinationType(DestinationType.FOLDER)
        .setDestinationId(destinationFolderId)
        .setNewName("newFolderName")
        .build();

// Copy folder (omit 'include' and 'skipRemap' parameters).
smartsheet.folderResources().copyFolder(folderId, destination, null, null);

// Copy folder (specify 'include' parameter with value of "all", and 'skipRemap' parameter with value of "cellLinks").
smartsheet.folderResources().copyFolder(folderId, destination, EnumSet.of(FolderCopyInclusion.ALL), EnumSet.of(FolderRemapExclusion.CELLLINKS));

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": 7116448184199044,
        "name": "newFolderName",
        "permalink": "https://{base_url}?lx=lB0JaOh6AX1wGwqxsQIMaA"
    },
    "message": "SUCCESS"
}

POST /folders/{folderId}/copy

Creates a copy of the specified Folder.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters include (optional) – a comma-separated list of elements to copy:
  • data
  • attachments
  • discussions
  • cellLinks
  • forms
  • all - specify a value of “all” to include everything (data, attachments, discussions, cellLinks, and forms)
Note: Cell history will not be copied, regardless of which include parameter values are specified.
skipRemap (optional) – – comma-separated list of references to NOT re-map for the newly created folder:
  • cellLinks
  • reports
By default, all cell links and reports that reference sheets in the source folder will be re-mapped to reference corresponding sheets in the newly created folder. The skipRemap parameter can be specified to change that default behavior:
  • If “cellLinks” is specified in the skipRemap parameter value, the cell links within the newly created folder will continue to point to the original source sheets.
  • If “reports” is specified in the skipRemap parameter value, the reports within the newly created folder will continue to point to the original source sheets.
Request Body ContainerDestination object
Returns Result object containing a Folder object for the newly created Folder

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"}'
// Set folder name.
var folder = {
    "name": "New folder"
};

// Set options.
var options = {
    body: folder
};

// Create folder in "Sheets" folder (Home).
smartsheet.home.createFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder("New folder").Build();

// Create folder in "Sheets" folder (Home).
smartsheet.HomeResources.FolderResources.CreateFolder(folder);
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder().setName("New Folder").build();

// Create folder in "Sheets" folder (Home).
smartsheet.homeResources().folderResources().createFolder(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"}'
// Set folder name.
var folder = {
    "name": "New folder"
};

// Set options.
var options = {
    body: folder,
    folderId: 7960873114331012
};

// Create folder in another folder.
smartsheet.folders.createChildFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder("New folder").Build();

// Create folder in another folder.
smartsheet.FolderResources.CreateFolder(destinationFolderId, folder);
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder().setName("New Folder").build();

// Create folder in another folder.
smartsheet.folderResources().createFolder(destinationFolderId, 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"}'
// Set folder name.
var folder = {
    "name": "New folder"
};

// Set options.
var options = {
    body: folder,
    workspaceId: 1656220827314052
};

// Create folder in a workspace.
smartsheet.workspaces.createFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder("New folder").Build();

// Create folder in a workspace.
smartsheet.WorkspaceResources.FolderResources.CreateFolder(workspaceId, folder);
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder().setName("New Folder").build();

// Create folder in a workspace.
smartsheet.workspaceResources().folderResources().createFolder(workspaceId, 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
// Set options.
var options = {
    id: 965780272637828 // ID of Folder
};

// Delete folder.
smartsheet.folders.deleteFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete folder.
smartsheet.FolderResources.DeleteFolder(folderId);
// Delete folder.
smartsheet.folderResources().deleteFolder(folderId);

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"
// Set options.
var options = {
    id: 7116448184199044 // ID of Folder
};

// Get folder.
smartsheet.folders.getFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get folder (omit 'include' parameter).
smartsheet.FolderResources.GetFolder(folderId, null);

// Get folder (specify 'include' parameter with value of "source").
smartsheet.FolderResources.GetFolder(folderId, new FolderInclusion[] { FolderInclusion.SOURCE });
// Get folder (omit 'include' parameter).
smartsheet.folderResources().getFolder(folderId, null)

// Get folder (specify 'include' parameter with value of "source").
smartsheet.folderResources().getFolder(folderId, EnumSet.of(SourceInclusion.SOURCE))

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",
            "createdAt": "2015-06-05T20:05:29Z",
            "modifiedAt": "2015-06-05T20:05:43Z"
        }
    ]
}

GET /folders/{folderId}

Gets the specified Folder (and lists its contents).

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional) – a comma-separated list of optional elements to include in the response:
  • ownerInfo - owner’s email address and user ID for each sheet
  • source - the source for any sheet that was created from another sheet or template
Returns Folder object, populated according to the include parameter

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"
// List folders in "Sheets" folder. 
smartsheet.home.listFolders()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// List folders in "Sheets" folder (omit pagination parameters).
smartsheet.HomeResources.FolderResources.ListFolders(null);

// List folders in "Sheets" folder (specify 'includeAll' parameter with value of "true").
smartsheet.HomeResources.FolderResources.ListFolders(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List folders (specify 'includeAll' parameter with value of "true").
smartsheet.homeResources().folderResources().listFolders(parameters);

// List folders (omit pagination parameters).
smartsheet.homeResources().folderResources().listFolders(null);

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"
// Set options.
var options = {
    folderId: 5107651446105988
};

// List folders in another folder.
smartsheet.folders.listChildFolders(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List folders in another folder (omit pagination parameters).
smartsheet.FolderResources.ListFolders(folderId, null);

// List folders in another folder (specify 'includeAll' parameter with value of "true").
smartsheet.FolderResources.ListFolders(folderId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List folders in another folder (specify 'includeAll' parameter with value of "true").
smartsheet.folderResources().listFolders(parameters);

// List folders in another folder (omit pagination parameters).
smartsheet.folderResources().listFolders(null);

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"
// Set options.
var options = {
    workspaceId: 1656220827314052
};

// List folders in workspace.
smartsheet.workspaces.listWorkspaceFolders(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List folders in workspace (omit pagination parameters).
smartsheet.WorkspaceResources.FolderResources.ListFolders(workspaceId, null);

// List folders in workspace (specify 'includeAll' parameter with value of "true").
smartsheet.WorkspaceResources.FolderResources.ListFolders(workspaceId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List folders in workspace (specify 'includeAll' parameter with value of "true").
smartsheet.workspaceResources().folderResources().listFolders(parameters);

// List folders in workspace (omit pagination parameters).
smartsheet.workspaceResources().folderResources().listFolders(null);

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

Move Folder

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId}/move \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ \
    "destinationType": "workspace|folder|home", \
    "destinationId": workspace_or_folder_id \
}' \
-X POST
// Specify destination.
ContainerDestination destination = new ContainerDestination
{
    DestinationId = destinationFolderId,
    DestinationType = DestinationType.FOLDER,
};

// Move folder.
smartsheet.FolderResources.MoveFolder(folderId, destination);
// Specify destination.
ContainerDestination destination = new ContainerDestination.AddContainerDestinationBuilder()
        .setDestinationType(DestinationType.FOLDER)
        .setDestinationId(destinationFolderId)
        .build();

// Move folder.
smartsheet.folderResources().moveFolder(folderId, destination);

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": 4509918431602564,
        "name": "moved_folder_name",
        "permalink": "https://{base_url}?lx=lB0JaOh6AX1wGwqxsQIMaA"
    },
    "message": "SUCCESS"
}

POST /folders/{folderId}/move

Moves the specified Folder to another location.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body ContainerDestination object, limited to the following required attributes:
  • destinationType
  • destinationId
Returns Result object containing a Folder object for the moved Folder

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"}'
// Set folder name.
var folder = {
    "name": "New name for folder"
};

// Set options.
var options = {
    id: 1486948649985924, // ID of Folder
    body: folder
};

// Update folder.
smartsheet.folders.updateFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set folder name.
Folder folder = new Folder.UpdateFolderBuilder(folderId, "New name for folder").Build();

// Update folder.
smartsheet.FolderResources.UpdateFolder(folder);
// Set folder name and id of the folder to be updated.
Folder folder = new Folder.UpdateFolderBuilder().setName("New name for folder").setId(folderId).build();

// Update folder.
smartsheet.folderResources().updateFolder(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" }]}'
// Specify group.
var group = {
    "name": "API-created Group",
    "description": "Group created via API",
    "members": [
        {
            "email": "john.doe@smartsheet.com"
        }
    ]
};

// Set options.
var options = {
    body: group
};

// Create group.
smartsheet.groups.createGroup(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create group member.
GroupMember member = new GroupMember.AddGroupMemberBuilder("john.doe@smartsheet.com").Build();

// Add member to group.
Group group = new Group.CreateGroupBuilder("API-created Group", "Group created via API").SetMembers(new GroupMember[] { member }).Build();

// Create group.
smartsheet.GroupResources.CreateGroup(group);
// Create group member.
GroupMember member = new GroupMember.AddGroupMemberBuilder().setEmail("john.doe@smartsheet.com").build(); 

// Add member to group.
Group group = new Group.CreateGroupBuilder().setName("API-created Group").setDescription("Group created via API").setMembers(Arrays.asList(member)).build();

// Create group.
smartsheet.groupResources().createGroup(group);

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
// Set options.
var options = {
    id: 6932724448552836 // ID of Group
};

// Delete group.
smartsheet.groups.deleteGroup(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete group.
smartsheet.GroupResources.DeleteGroup(groupId);
// Delete group.
smartsheet.groupResources().deleteGroup(groupId);

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"
// Set options.
var options = {
    id: 4583173393803140 // ID of Group
};

// Get group.
smartsheet.groups.getGroup(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get group.
smartsheet.GroupResources.GetGroup(groupId);
// Get group.
smartsheet.groupResources().getGroup(groupId);

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"
// List all org groups.
smartsheet.groups.listGroups()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List all org groups (omit pagination parameters).
smartsheet.GroupResources.ListGroups(null);

// List all org groups (specify 'includeAll' parameter with value of "true").
smartsheet.GroupResources.ListGroups(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List all org groups (specify 'includeAll' parameter with value of "true").
smartsheet.groupResources().listGroups(parameters);

// List all org groups (omit pagination parameters).
smartsheet.groupResources().listGroups(null);

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" }'
// Specify the name and description of the group.
var group = {
    "name": "Renamed Group",
    "description": "Some new description"
};

// Set options.
var options = {
    body: group,
    id: 2331373580117892 // ID of Group
};

// Update group.
smartsheet.groups.updateGroup(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify the name and description of the group.
Group group = new Group.UpdateGroupBuilder(groupId).SetName("Renamed Group").SetDescription("Some new description").Build();

// Update group.
smartsheet.GroupResources.UpdateGroup(group);
// Specify the name and description of the group.
Group group = new Group.UpdateGroupBuilder().setId(groupId).setName("Renamed Group").setDescription("Some new description").build();

// Update group.
smartsheet.groupResources().updateGroup(group);

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" }]'
// Specify group member(s).
var members = [{ "email": "jane.doe@smartsheet.com" }];

// Set options.
var options = {
    body: members,
    groupId: 7917992160847748
};

// Add member(s) to group.
smartsheet.groups.addGroupMembers(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create group member.
GroupMember member = new GroupMember.AddGroupMemberBuilder("jane.doe@smartsheet.com").Build();

// Add member(s) to group.
smartsheet.GroupResources.AddGroupMembers(groupId, new GroupMember[] { member });
// Create group member.
GroupMember member = new GroupMember.AddGroupMemberBuilder().setEmail("jane.doe@smartsheet.com").build();

// Add member(s) to group.
smartsheet.groupResources().memberResources().addGroupMembers(groupId, Arrays.asList(member));

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
// Set options.
var options = {
    groupId: 7917992160847748,
    userId: 1539725208119172
};

// Remove member from group.
smartsheet.groups.removeGroupMember(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove member from group.
smartsheet.GroupResources.RemoveGroupMember(groupId, userId);
// Remove member from group.
smartsheet.groupResources().memberResources().deleteGroupMember(groupId, userId)

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"
// List all contents.
smartsheet.home.listContents()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// List all contents (omit 'include' parameter).
smartsheet.HomeResources.GetHome(null);

// List all contents (specify 'include' parameter with value of "source").
smartsheet.HomeResources.GetHome(new HomeInclusion[] { HomeInclusion.SOURCE });
// List all contents (omit 'include' parameter).
smartsheet.homeResources().getHome(null);

// List all contents (specify 'include' parameter with value of "source").
smartsheet.homeResources().getHome(EnumSet.of(SourceInclusion.SOURCE)));

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", 
            "createdAt": "2015-06-05T20:05:29Z",
            "modifiedAt": "2015-06-05T20:05:43Z"
        },
        {
            "id": 2331373580117892,
            "name": "Copy of sheet 1",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=Dsje3YKtpyZScrCX6Zb",
            "createdAt": "2015-06-05T20:05:29Z",
            "modifiedAt": "2015-06-05T20:05:43Z",
            "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) – a comma-separated list of optional elements to include in the response:
  • ownerInfo - owner’s email address and user ID for each sheet
  • source - 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"
// Set options.
var options = {
    id: 4583173393803140 // ID of Report
};

// Get report.
smartsheet.reports.getReport(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get report (omit 'include', 'pageSize', and 'page' parameters).
smartsheet.ReportResources.GetReport(reportId, null, null, null);

// Get report (specify 'include' parameter with value of "attachments" and "discussions", 'pageSize' parameter with value of "500", and 'page' of value "2").
smartsheet.ReportResources.GetReport(reportId, new ReportInclusion[] { ReportInclusion.ATTACHMENTS, ReportInclusion.DISCUSSIONS }, 500, 2);
// Get report (omit 'include', 'pageSize', and 'page' parameters).
smartsheet.reportResources().getReport(reportId, null, null, null);

// Get report (specify 'include' parameter with value of "attachments" and "discussions", 'pageSize' parameter with value of "500", and 'page' of value "2").
smartsheet.reportResources().getReport(reportId, EnumSet.of(ReportInclusion.ATTACHMENTS, ReportInclusion.DISCUSSIONS), 500, 2)

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 elements 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
// Set options.
var options = {
    id: 3882962191181700 // ID of Report
};

// Get report as Excel.
smartsheet.reports.getReportAsExcel(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get report as Excel.
smartsheet.ReportResources.GetReportAsExcel(reportId, outputStream);
// Get report as Excel.
smartsheet.reportResources().getReportAsExcel(reportId, outputStream);

Example Response:

# See local file named "output.xls"
// [todo]
// Contents of Excel file will be written to "outputStream"
// Contents of Excel file will be written to "outputStream"

Example Request (CSV):

curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: text/csv" \
-o output.csv
// Set options.
var options = {
    id: 3882962191181700 // ID of Report
};

// Get report as CSV.
smartsheet.reports.getReportAsCSV(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get report as CSV.
smartsheet.ReportResources.GetReportAsCSV(reportId, outputStream);
// Get report as CSV.
smartsheet.reportResources().getReportAsCsv(reportId, outputStream);

Example Response:

# See local file named "output.csv"
// [todo]
// Contents of CSV file will be written to "outputStream"
// Contents of CSV file will be written to "outputStream"

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
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"
// List reports.
smartsheet.reports.listReports()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List reports (omit pagination parameters).
smartsheet.ReportResources.ListReports(null);

// List reports (specify 'includeAll' parameter with value of "true").
smartsheet.ReportResources.ListReports(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List reports (specify 'includeAll' parameter with value of "true").
smartsheet.reportResources().listReports(parameters);

// List reports (omit pagination parameters).
smartsheet.reportResources().listReports(null);

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"}}'
// Configure email.
var email = {
    "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"
    }
};

// Set options.
var options = {
    body: email,
    reportId: 8130994621441924
};

// Send report via email.
smartsheet.reports.sendReportViaEmail(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "john.doe@smartsheet.com" }, 
    new Recipient { GroupId = 2258118617917316 } 
};

// Configure email.
SheetEmail sheetEmail = new SheetEmail { 
    SendTo = recipients, 
    Subject = "Check this report out!", 
    Message = "Here is the report I mentioned in our meeting", 
    CcMe = false, 
    Format = SheetEmailFormat.PDF, 
    FormatDetails = new FormatDetails { PaperSize = PaperSize.A4 } 
};

// Send report via email.
smartsheet.ReportResources.SendReport(reportId, sheetEmail);
// Specify an individual recipient.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("john.doe@smartsheet.com").build();

// Specify a group recipient.
RecipientGroup recipientGroup = new RecipientGroup.AddRecipientGroupBuilder().setGroupId(2258118617917316).build();

/// Set recipients.
List<Recipient> recipients = Arrays.asList(recipientEmail, recipientGroup);

// Set format details.
FormatDetails formatDetails = new FormatDetails();
formatDetails.setPaperSize(PaperSize.A0); 

// Configure email.
SheetEmail email = new SheetEmail.AddSheetEmailBuilder()
    .setSendTo(recipients)
    .setSubject("Check this report out!")
    .setMessage("Here is the report I mentioned in our meeting")
    .setCcMe(false)
    .setFormat(SheetEmailFormat.PDF)
    .setFormatDetails(formatDetails)
    .build();

// Send report via email.
smartsheet.reportResources().sendReport(reportId, email)

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)
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 Flag indicating whether the row is locked. In a response, a value of true indicates that the row has been locked by the sheet owner or the admin.
lockedForUser boolean Flag indicating whether the row is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.
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.
permalink string URL that represents a direct link to the Row in Smartsheet
Only returned if the include query string parameter contains rowPermalink.
parentId number In a response - the ID of the parent row (if any).

In a request - the ID of the desired parent row (used to specify the location for a new or moved row). For more information, see Row Location.
siblingId number In a response - the ID of the previous sibling row at the same hierarchical level of this row (if any).

In a request - the ID of the desired sibling row (used to specify the location for a new or moved row). For more information, see Row Location.
toTop boolean Flag used to specify the location for a new or moved row. This attribute can be specified in a request, but will never be present in a response. For more information, see Row Location.
toBottom boolean Flag used to specify the location for a new or moved row. This attribute can be specified in a request, but will never be present in a response. For more information, see Row Location.
above boolean Flag used to specify the location for a new or moved row. This attribute can be specified in a request, but will never be present in a response. For more information, see Row Location.

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} ] }]'
// Specify rows.
var row = [
    {
        "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
            }
        ]
    }
];

// Set options.
var options = {
    body: row,
    sheetId: 2252168947361668
};

// Add rows to sheet.
smartsheet.sheets.addRows(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify cell values for first row.
Cell[] cellsA = new Cell[] { new Cell.AddCellBuilder(7960873114331012, true).Build(), new Cell.AddCellBuilder(642523719853956, "New status").SetStrict(false).Build() };

// Specify contents of first row.
Row rowA = new Row.AddRowBuilder(true, null, null, null, null).SetCells(cellsA).Build();

// Specify cell values of second row.
Cell[] cellsB = new Cell[] { new Cell.AddCellBuilder(7960873114331012, true).Build(), new Cell.AddCellBuilder(642523719853956, "New status").SetStrict(false).Build() };

// Specify contents of second row.
Row rowB = new Row.AddRowBuilder(true, null, null, null, null).SetCells(cellsB).Build();

// Add rows to sheet.
smartsheet.SheetResources.RowResources.AddRows(sheetId, new Row[] { rowA, rowB });
// Specify cell values for first row.
List<Cell> cellsA = new Cell.AddRowCellsBuilder().addCell(7960873114331012, true).addCell(642523719853956, "New status").build();

// Specify contents of first row.
Row rowA = new Row.AddRowBuilder().setCells(cellsA).setToBottom(true).build();

// Specify cell values for second row.
List<Cell> cellsB = new Cell.AddRowCellsBuilder().addCell(7960873114331012, true).addCell(642523719853956, "New status").build();

// Specify contents of second row.
Row rowB = new Row.AddRowBuilder().setCells(cellsB).setToBottom(true).build();

// Add rows to sheet.
smartsheet.sheetResources().rowResources().addRows(sheetId, Arrays.asList(rowA, rowB));

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:
  • One or more location-specifier attributes (optional)
  • format (optional)
  • expanded (optional)
  • locked (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} }'
// Specify the directive.
var copyRow = {
    "rowIds": [145417762563972, 8026717110462340],
    "to": {
        "sheetId": 2258256056870788
    }
};

// Set options.
var options = {
    body: copyRow,
    sheetId: 2252168947361668
};

// Copy rows.
smartsheet.sheets.copyRowToAnotherSheet(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify destination sheet.
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination { SheetId = 2258256056870788 };

// Specify rows to be copied (and destination sheet).
CopyOrMoveRowDirective directive = new CopyOrMoveRowDirective { RowIds = new long[] { 145417762563972, 8026717110462340 }, To = destination };

// Copy rows (omit 'include' and 'ignoreRowsNotFound' parameters).
smartsheet.SheetResources.RowResources.CopyRowsToAnotherSheet(sheetId, directive, null, null);

// Copy rows (specify 'include' parameter with value of "children", and 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.SheetResources.RowResources.CopyRowsToAnotherSheet(sheetId, directive, new CopyRowInclusion[] { CopyRowInclusion.CHILDREN }, true);
// Specify destination sheet.
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination.InsertCopyOrMoveRowDestinationBuilder().setSheetId(2258256056870788).build();

// Specify rows to be copied (and destination sheet).
CopyOrMoveRowDirective directive = new CopyOrMoveRowDirective.InsertCopyOrMoveRowDirectiveBuilder().setRowIds(Arrays.asList(145417762563972, 8026717110462340)).setTo(destination).build();

// Copy rows (omit 'include' and 'ignoreRowsNotFound' parameters).
smartsheet.sheetResources().rowResources().copyRows(sheetId, null, null, directive);

// Copy rows (specify 'include' parameter with value of "children", and 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.sheetResources().rowResources().copyRows(sheetId, EnumSet.of(RowCopyInclusion.CHILDREN), true, directive);

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.
  • all - specify a value of “all” to include everything (attachments, discussions, and children)
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(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows?ids={rowId1},{rowId2},{rowId3}&ignoreRowsNotFound=true \
-X DELETE
// Set options.
var options = {
    sheetId: 2252168947361668,
    rowId: 207098194749316
};

// Delete row.
smartsheet.sheets.deleteRow(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete rows (specify 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.SheetResources.RowResources.DeleteRows(sheetId, new long[] { rowId1, rowId2, rowId3 }, true);
// Delete rows (specify 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.sheetResources().rowResources().deleteRows(sheetId, new HashSet(Arrays.asList(rowId1, rowId2, rowId3), true);

Example Response:

{
    "resultCode": 0,
    "result": [
        145417762563972,
        4508365800925060,
        8026717110462340,
        2256565987239812 
    ],
    "message": "SUCCESS"
}

DELETE /sheets/{sheetId}/rows?ids={rowId1},{rowId2},{rowId3}...

Deletes one or more row(s) from the Sheet specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters ids (required) - comma-separated list of Row IDs
ignoreRowsNotFound (optional) - true or false. If set to false and any of the specified Row IDs are not found, no rows will be deleted, and the “not found” error will be returned.
Returns Result object containing Row IDs corresponding to all rows that were successfully deleted (including any child rows of rows specified in the URL).

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"
// Set options.
var options = {
    sheetId: 4583173393803140,
    rowId: 2361756178769796
};

// Get row.
smartsheet.sheets.getRow(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get row (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.RowResources.GetRow(sheetId, rowId, null, null);

// Get row (specify 'include' parameter with values of "columns" and "columnType", and 'exclude' parameter with value of "nonexistentCells").
smartsheet.SheetResources.RowResources.GetRow(sheetId, rowId, new RowInclusion[] { RowInclusion.COLUMNS, RowInclusion.COLUMN_TYPE }, new ObjectExclusion[] { ObjectExclusion.NONEXISTENT_CELLS });
// Get row (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().rowResources().getRow(sheetId, rowId, null, null);

// Get row (specify 'include' parameter with values of "columns" and "columnType", and 'exclude' parameter with value of "nonexistentCells").
smartsheet.sheetResources().rowResources().getRow(sheetId, rowId, EnumSet.of(RowInclusion.COLUMNS, RowInclusion.COLUMN_TYPE), EnumSet.of(ObjectExclusion.NONEXISTENT_CELLS));

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} }'
// Specify the directive.
var moveRow = {
    "rowIds": [145417762563972, 8026717110462340],
    "to": {
        "sheetId": 2258256056870788
    }
};

// Set options.
var options = {
    body: moveRow,
    sheetId: 2252168947361668
};

// Move rows.
smartsheet.sheets.moveRowToAnotherSheet(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    }
// Specify destination sheet.
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination { SheetId = 2258256056870788 };

// Specify rows to be moved (and destination sheet).
CopyOrMoveRowDirective directive = new CopyOrMoveRowDirective { RowIds = new long[] { 145417762563972, 8026717110462340 }, To = destination };

// Move rows (omit 'include' and 'ignoreRowsNotFound' parameters).
smartsheet.SheetResources.RowResources.MoveRowsToAnotherSheet(sheetId, directive, null, null);

// Move rows (specify 'include' parameter with value of "attachments" and "discussions", and 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.SheetResources.RowResources.MoveRowsToAnotherSheet(sheetId, directive, new MoveRowInclusion[] { MoveRowInclusion.ATTACHMENTS, MoveRowInclusion.DISCUSSIONS }, true);
// Specify destination sheet.
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination.InsertCopyOrMoveRowDestinationBuilder().setSheetId(2258256056870788).build();

// Specify rows to be moved (and destination sheet).
CopyOrMoveRowDirective directive = new CopyOrMoveRowDirective.InsertCopyOrMoveRowDirectiveBuilder().setRowIds(Arrays.asList(145417762563972, 8026717110462340)).setTo(destination).build();

// Move rows (omit 'include' and 'ignoreRowsNotFound' parameters).
smartsheet.sheetResources().rowResources().moveRows(sheetId, null, null, directive);

// Move rows (specify 'include' parameter with value of "attachments" and "discussions", and 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.sheetResources().rowResources().moveRows(sheetId, EnumSet.of(EnumSet.of(RowMoveInclusion.ATTACHMENTS, RowMoveInclusion.DISCUSSIONS)), true, directive);

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(s) via Email

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient@smartsheet.com"} \
    ], \
    "subject": "some subject", \
    "message": "some message", \
    "ccMe": false, \
    "rowIds": [ \
        rId1, \
        rId2 \
    ], \
    "columnIds": [ \
        cId1, \
        cId2 \
    ], \
    "includeAttachments": false, \
    "includeDiscussions": false \
}'
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "recipient@smartsheet.com" }, 
};

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail {
    SendTo = recipients,
    Subject = "some subject",
    Message = "some message",
    CcMe = false,
    RowIds = new long[] { rowId1, rowId2 },
    ColumnIds = new long[] { columnId1, columnId2 },
    IncludeAttachments = false,
    IncludeDiscussions = false
};

// Send rows via email.
smartsheet.SheetResources.RowResources.SendRows(sheetId, multiRowEmail);
// Specify recipients.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("recipient@smartsheet.com").build();

List<Recipient> recipients = new ArrayList<Recipient>();
recipients.add(recipientEmail);

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()
    .setSendTo(recipients)
    .setSubject("some subject")
    .setMessage("some message")
    .setCcMe(false)
    .setRowIds(Arrays.asList(rowId1, rowId2)
    .setColumnIds(Arrays.asList(columnId1, columnId2)
    .setIncludeAttachments(false)
    .setIncludeDiscussions(false)
    .build();

// Send rows via email.
smartsheet.sheetResources().rowResources().sendRows(sheetId, multiRowEmail);

Example Response:

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

POST /sheets/{sheetId}/rows/emails

Sends one or more Rows via email.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body MultiRowEmail object.

The columns included for each row in the email will be populated according to the following rules:
  • If the columnIds attribute of the MultiRowEmail object is specified as an array of column IDs, those specific columns will be included.
  • If the columnIds attribute of the MultiRowEmail object is omitted, all columns except hidden columns shall be included.
  • If the columnIds attribute of the MultiRowEmail object is specified as empty, no columns shall be included. (Note: In this case, either includeAttachments:true or includeDiscussions:true must be specified.)
Returns Result object

Send Update Request

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "email789@smartsheet.com"}, \
        {"email": "email0123@smartsheet.com"} \
    ], \
    "subject": "some subject", \
    "message": "some message", \
    "ccMe": (true|false), \
    "rowIds": [rowId1, rowId2], \
    "columnIds": [colId1, colId2], \
    "includeAttachments": (true|false), \
    "includeDiscussions": (true|false) \
}'
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "email789@smartsheet.com" },
    new Recipient { Email = "email0123@smartsheet.com" }
};

// Configure email.
MultiRowEmail multiEmail = new MultiRowEmail {
    SendTo = recipients,
    Subject = "some subject",
    Message = "some message",
    CcMe = true,
    RowIds = new long[] { rowId1, rowId2 },
    ColumnIds = new long[] { colId1, colId2 },
    IncludeAttachments = true,
    IncludeDiscussions = true
};

// Send update request via email.
smartsheet.SheetResources.SendUpdateRequest(sheetId, multiEmail);
// Specify recipients.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder()
                .setEmail("email789@smartsheet.com")
                .setEmail("email0123@smartsheet.com")
                .build();

List<Recipient> recipients = new ArrayList<Recipient>();
recipients.add(recipientEmail);

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()
    .setSendTo(recipients)
    .setSubject("some subject")
    .setMessage("some message")
    .setCcMe(false)
    .setRowIds(Arrays.asList(rowId1, rowId2)
    .setColumnIds(Arrays.asList(columnId1, columnId2)
    .setIncludeAttachments(false)
    .setIncludeDiscussions(false)
    .build();

// Send update request via email.
smartsheet.sheetResources().createUpdateRequest(sheetId, multiRowEmail);

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": 4583173393803140
    },
    "message": "SUCCESS"
}

POST /sheets/{sheetId}/updaterequests

Creates an Update Request for the specified Row(s) within the Sheet. An email notification (containing a link to the update request) will be asynchronously sent to the specified recipient(s).

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body MultiRowEmail object

The MultiRowEmail object in the request body must specify one or more of the following attributes:
  • columnIds: number[]
  • attachments: true
  • discussions: true
Returns Result object containing the newly created UpdateRequest 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"}]}]'
// Specify updated cell values.
var row = [
    {
        "id": "6572427401553796",
        "cells": [
            {
                "columnId": 7518312134403972,
                "value": "new value"
            },
            {
                "columnId": 1888812600190852,
                "value": "A"
            }
        ]
    },
    {
        "id": "2068827774183300",
        "cells": [
            {
                "columnId": 7518312134403972,
                "value": "desc_updated"
            },
            {
                "columnId": 1888812600190852,
                "value": "B"
            }
        ]
    }
];

// Set options.
var options = {
    body: row,
    sheetId: 2252168947361668
};

// Update rows in sheet.
smartsheet.sheets.updateRow(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify updated cell values for first row.
Cell[] cellsA = new Cell[] { new Cell.UpdateCellBuilder(7518312134403972, "new value").Build(), new Cell.UpdateCellBuilder(1888812600190852, "A").Build() };

// Specify updated contents of first row.
Row rowA = new Row.UpdateRowBuilder(6572427401553796).SetCells(cellsA).Build();

// Specify updated cell values for second row.
Cell[] cellsB = new Cell[] { new Cell.UpdateCellBuilder(7518312134403972, "desc_updated").Build(), new Cell.UpdateCellBuilder(1888812600190852, "B").Build() };

// Specify updated contents of second row.
Row rowB = new Row.UpdateRowBuilder(2068827774183300).SetCells(cellsB).Build();

// Update rows in sheet.
smartsheet.SheetResources.RowResources.UpdateRows(sheetId, new Row[] { rowA, rowB });
// Specify updated cell values for first row.
List<Cell> cellsA = new Cell.UpdateRowCellsBuilder().addCell(7518312134403972, "new value").addCell(1888812600190852, "A").build();

// Specify updated contents of first row.
Row rowA = new Row.UpdateRowBuilder().setCells(cellsA).setRowId(6572427401553796).build();

// Specify updated cell values for second row.
List<Cell> cellsB = new Cell.UpdateRowCellsBuilder().addCell(7518312134403972, "desc_updated").addCell(1888812600190852, "B").build();

// Specify updated contents of second row.
Row rowB = new Row.UpdateRowBuilder().setCells(cellsB).setRowId(2068827774183300).build();

// Update rows in sheet.
smartsheet.sheetResources().rowResources().updateRows(sheetId, Arrays.asList(rowA, rowB));

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": "new value"
                },
                {
                    "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:
  • One or more location-specifier attributes (optional)
  • expanded (optional)
  • format (optional)
  • 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.
rowPermalink Includes permalink attribute that represents a direct link to the row in the Smartsheet application.

Row Location

When using the Add Row(s) operation to insert new rows into a sheet or the Update Row(s) to move rows in a sheet, the following “location-specifier” Row attributes can be used to specify where the rows get added or moved to in the sheet:

  • toTop
  • toBotom
  • above
  • siblingId
  • parentId

The following table describes which location-specifier Row attribute(s) should be set to implement various actions.

Action Row attribute(s)
Add or move the Row to the top of the Sheet. toTop = true
Add or move the Row to the bottom of the Sheet. toBottom = true
Add or move the Row directly above the specified sibling Row (at the same hierarchical level). above = true
siblingId = (ID of sibling row)
Add or move the Row directly below the specified sibling Row (at the same hierarchical level). siblingId = (ID of sibling row)
Add or move the Row so that it is the first child row of the specified parent Row. parentId = (ID of parent row)
Add or move the Row so that it is the last child row of the specified parent Row. parentId = (ID of parent row)
toBottom = true

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"
// Set options.
var options = {
    query: "stuff"
};

// Search everything.
smartsheet.search.searchAll(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set search criteria.
string query = "stuff";

// Search everything.
smartsheet.SearchResources.Search(query);
// Set search criteria.
string query = "stuff";

// Search everything.
smartsheet.searchResources().search(query);

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"
// Set options.
var options = {
    sheetId: 1888207043356548,
    queryParameters: {
        query: "stuff"
    }
};

// Search sheet.
smartsheet.search.searchSheet(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set search criteria.
string query = "stuff";

// Search sheet.
smartsheet.SearchResources.SearchSheet(sheetId, query);
// Set search criteria.
string query = "stuff";

// Search sheet.
smartsheet.searchResources().searchSheet(sheetId, query);

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:

columnIds number[] IDs of the columns to be included.
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.

MultiRowEmail Object

Extends the RowEmail object, adding the following:

rowIds number[] IDs of rows to be included.

SheetEmail Object

Extends the Email object, adding the following:

format string One of the following values:
  • PDF
  • PDF_GANTT
  • 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"}}'
// Configure email.
var email = {
    "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"
    }
};

// Set options.
var options = {
    body: email,
    reportId: 8130994621441924
};

// Send report via email.
smartsheet.reports.sendReportViaEmail(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "john.doe@smartsheet.com" }, 
    new Recipient { GroupId = 2258118617917316 } 
};

// Configure email.
SheetEmail sheetEmail = new SheetEmail { 
    SendTo = recipients, 
    Subject = "Check this report out!", 
    Message = "Here is the report I mentioned in our meeting", 
    CcMe = false, 
    Format = SheetEmailFormat.PDF, 
    FormatDetails = new FormatDetails { PaperSize = PaperSize.A4 } 
};

// Send report via email.
smartsheet.ReportResources.SendReport(reportId, sheetEmail);
// Specify an individual recipient.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("john.doe@smartsheet.com").build();

// Specify a group recipient.
RecipientGroup recipientGroup = new RecipientGroup.AddRecipientGroupBuilder().setGroupId(2258118617917316).build();

/// Set recipients.
List<Recipient> recipients = Arrays.asList(recipientEmail, recipientGroup);

// Set format details.
FormatDetails formatDetails = new FormatDetails();
formatDetails.setPaperSize(PaperSize.A0); 

// Configure email.
SheetEmail email = new SheetEmail.AddSheetEmailBuilder()
    .setSendTo(recipients)
    .setSubject("Check this report out!")
    .setMessage("Here is the report I mentioned in our meeting")
    .setCcMe(false)
    .setFormat(SheetEmailFormat.PDF)
    .setFormatDetails(formatDetails)
    .build();

// Send report via email.
smartsheet.reportResources().sendReport(reportId, email)

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(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient@smartsheet.com"} \
    ], \
    "subject": "some subject", \
    "message": "some message", \
    "ccMe": false, \
    "rowIds": [ \
        rId1, \
        rId2 \
    ], \
    "columnIds": [ \
        cId1, \
        cId2 \
    ], \
    "includeAttachments": false, \
    "includeDiscussions": false \
}'
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "recipient@smartsheet.com" }, 
};

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail {
    SendTo = recipients,
    Subject = "some subject",
    Message = "some message",
    CcMe = false,
    RowIds = new long[] { rowId1, rowId2 },
    ColumnIds = new long[] { columnId1, columnId2 },
    IncludeAttachments = false,
    IncludeDiscussions = false
};

// Send rows via email.
smartsheet.SheetResources.RowResources.SendRows(sheetId, multiRowEmail);
// Specify recipients.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("recipient@smartsheet.com").build();

List<Recipient> recipients = new ArrayList<Recipient>();
recipients.add(recipientEmail);

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()
    .setSendTo(recipients)
    .setSubject("some subject")
    .setMessage("some message")
    .setCcMe(false)
    .setRowIds(Arrays.asList(rowId1, rowId2)
    .setColumnIds(Arrays.asList(columnId1, columnId2)
    .setIncludeAttachments(false)
    .setIncludeDiscussions(false)
    .build();

// Send rows via email.
smartsheet.sheetResources().rowResources().sendRows(sheetId, multiRowEmail);

Example Response:

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

POST /sheets/{sheetId}/rows/emails

Sends one or more Rows via email.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body MultiRowEmail object.

The columns included for each row in the email will be populated according to the following rules:
  • If the columnIds attribute of the MultiRowEmail object is specified as an array of column IDs, those specific columns will be included.
  • If the columnIds attribute of the MultiRowEmail object is omitted, all columns except hidden columns shall be included.
  • If the columnIds attribute of the MultiRowEmail object is specified as empty, no columns shall be included. (Note: In this case, either includeAttachments:true or includeDiscussions:true must be specified.)
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"}}'

// Configure email.
var email = {
    "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"
    }
};

// Set options.
var options = {
    body: email,
    sheetId: 2252168947361668
};

// Send sheet via email.
smartsheet.sheets.sendSheetViaEmail(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "john.doe@smartsheet.com" }, 
    new Recipient { GroupId = 2258118617917316 } 
};

// Configure email.
SheetEmail sheetEmail = new SheetEmail { 
    SendTo = recipients, 
    Subject = "Check this report out!", 
    Message = "Here are the rows I mentioned in our meeting", 
    CcMe = false, 
    Format = SheetEmailFormat.PDF, 
    FormatDetails = new FormatDetails { PaperSize = PaperSize.A4 } 
};

// Send sheet via email.
smartsheet.SheetResources.SendSheet(sheetId, sheetEmail);
// Specify individual recipient.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("john.doe@smartsheet.com").build();

// Specify group recipient.
RecipientGroup recipientGroup = new RecipientGroup.AddRecipientGroupBuilder().setGroupId(2258118617917316).build();

// Set recipients.
List<Recipient> recipients = Arrays.asList(recipientEmail, recipientGroup);

// Set format details.
FormatDetails formatDetails = new FormatDetails();
formatDetails.setPaperSize(PaperSize.A0); 

// Configure email.
SheetEmail email = new SheetEmail.AddSheetEmailBuilder()
    .setSendTo(recipients)
    .setSubject("Check these rows out!")
    .setMessage("Here are the rows I mentioned in our meeting")
    .setCcMe(false)
    .setFormat(SheetEmailFormat.PDF)
    .setFormatDetails(formatDetails)
    .build();

// Send sheet via email.
smartsheet.sheetResources().sendSheet(sheetId, email);

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

Send Update Request

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "email789@smartsheet.com"}, \
        {"email": "email0123@smartsheet.com"} \
    ], \
    "subject": "some subject", \
    "message": "some message", \
    "ccMe": (true|false), \
    "rowIds": [rowId1, rowId2], \
    "columnIds": [colId1, colId2], \
    "includeAttachments": (true|false), \
    "includeDiscussions": (true|false) \
}'
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "email789@smartsheet.com" },
    new Recipient { Email = "email0123@smartsheet.com" }
};

// Configure email.
MultiRowEmail multiEmail = new MultiRowEmail {
    SendTo = recipients,
    Subject = "some subject",
    Message = "some message",
    CcMe = true,
    RowIds = new long[] { rowId1, rowId2 },
    ColumnIds = new long[] { colId1, colId2 },
    IncludeAttachments = true,
    IncludeDiscussions = true
};

// Send update request via email.
smartsheet.SheetResources.SendUpdateRequest(sheetId, multiEmail);
// Specify recipients.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder()
                .setEmail("email789@smartsheet.com")
                .setEmail("email0123@smartsheet.com")
                .build();

List<Recipient> recipients = new ArrayList<Recipient>();
recipients.add(recipientEmail);

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()
    .setSendTo(recipients)
    .setSubject("some subject")
    .setMessage("some message")
    .setCcMe(false)
    .setRowIds(Arrays.asList(rowId1, rowId2)
    .setColumnIds(Arrays.asList(columnId1, columnId2)
    .setIncludeAttachments(false)
    .setIncludeDiscussions(false)
    .build();

// Send update request via email.
smartsheet.sheetResources().createUpdateRequest(sheetId, multiRowEmail);

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": 4583173393803140
    },
    "message": "SUCCESS"
}

POST /sheets/{sheetId}/updaterequests

Creates an Update Request for the specified Row(s) within the Sheet. An email notification (containing a link to the update request) will be asynchronously sent to the specified recipient(s).

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body MultiRowEmail object

The MultiRowEmail object in the request body must specify one or more of the following attributes:
  • columnIds: number[]
  • attachments: true
  • discussions: true
Returns Result object containing the newly created UpdateRequest 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
// Get server info.
smartsheet.server.getInfo()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get server info.
smartsheet.ServerInfoResources.GetServerInfo();
// Get server info.
smartsheet.serverInfoResources().getServerInfo();

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
// Set options.
var options = {
    reportId: 665829219035012,
    shareId: "AAAQSF82F1eE"
};

// Delete report share.
smartsheet.reports.deleteShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete report share.
smartsheet.ReportResources.ShareResources.DeleteShare(reportId, shareId);
// Delete report share.
smartsheet.reportResources().shareResources().deleteShare(reportId, shareId);

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" 
// Set options.
var options = {
    reportId: 6932724448552836,
    shareId: "AQAISF82FOeE"
};

// Get report share.
smartsheet.reports.getShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get report share.
smartsheet.ReportResources.ShareResources.GetShare(reportId, shareId);
// Get report share.
smartsheet.reportResources().shareResources().getShare(reportId, shareId);

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" 
// Set options.
var options = {
    reportId: 665829219035012
};

// List report shares.
smartsheet.reports.listShares(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List report shares (omit pagination parameters).
smartsheet.ReportResources.ShareResources.ListShares(reportId, null);

// List report shares (specify 'includeAll' parameter with value of "true").
smartsheet.ReportResources.ShareResources.ListShares(reportId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List report shares (specify 'includeAll' parameter with value of "true").
smartsheet.reportResources().shareResources().listShares(reportId, parameters);

// List report shares (omit pagination parameters).
smartsheet.reportResources().shareResources().listShares(reportId, null);

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"}]'
// Specify share (to one user as Editor).
var share = [
    {
        "email": "jane.doe@smartsheet.com", 
        "accessLevel": "EDITOR"
    }
];

// Set options.
var options = {
    body: share,
    reportId: 665829219035012
};

// Share report.
smartsheet.reports.share(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify share (to one user as Editor).
Share[] shares = new Share[] { new Share.CreateShareBuilder("jane.doe@smartsheet.com", AccessLevel.EDITOR).Build() };

// Share report.
smartsheet.ReportResources.ShareResources.ShareTo(reportId, shares, true);
// Specify share (to one user as Editor).
List<Share> shares = Arrays.asList(new Share.CreateUserShareBuilder().setEmailAddress("jane.doe@smartsheet.com").setAccessLevel(AccessLevel.EDITOR).build());

// Share report.
smartsheet.reportResources().shareResources().shareTo(reportId, shares, true);

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"}'
// Set the access level to Viewer.
var share = {"accessLevel": "VIEWER"};

// Set options.
var options = {
    body: share,
    reportId: 665829219035012,
    shareId: "AAAFeF82FOeE"
};

// Update report share.
smartsheet.reports.updateShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set the access level to Viewer.
Share share = new Share.UpdateShareBuilder(shareId, AccessLevel.VIEWER).Build();

// Update report share.
smartsheet.ReportResources.ShareResources.UpdateShare(reportId, share);
// Set the access level to Viewer.
Share share = new Share.UpdateShareBuilder().setShareId(shareId).setAccessLevel(AccessLevel.VIEWER).build();

// Update report share.
smartsheet.reportResources().shareResources().updateShare(reportId, share);

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
// Set options.
var options = {
    sheetId: 4583614634583940,
    shareId: "AAAASuWWFOeE"
};

// Delete sheet share.
smartsheet.sheets.deleteShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete sheet share.
smartsheet.SheetResources.ShareResources.DeleteShare(sheetId, shareId);
// Delete sheet share.
smartsheet.sheetResources().shareResources().deleteShare(sheetId, shareId);

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" 
// Set options.
var options = {
    sheetId: 4583614634583940,
    shareId: "AQAISF82FOeE"
};

// Get sheet share.
smartsheet.sheets.getShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get sheet share.
smartsheet.SheetResources.ShareResources.GetShare(sheetId, shareId);
// Get sheet share.
smartsheet.sheetResources().shareResources().getShare(sheetId, shareId);

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" 
// Set options.
var options = {
    sheetId: 4583614634583940
};

// List sheet shares.
smartsheet.sheets.listShares(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List sheet shares (omit pagination parameters).
smartsheet.SheetResources.ShareResources.ListShares(sheetId, null);

// List sheet shares (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.ShareResources.ListShares(sheetId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List sheet shares (specify 'includeAll' parameter with value of "true").
smartsheet.sheetResources().shareResources().listShares(sheetId, parameters);

// List sheet shares (omit pagination parameters).
smartsheet.sheetResources().shareResources().listShares(sheetId, null);

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"}]'
// Specify share (to one user as Editor).
var share = [
    {
        "email": "jane.doe@smartsheet.com", 
        "accessLevel": "EDITOR"
    }
];

// Set options.
var options = {
    body: share,
    sheetId: 4583614634583940
};

// Share sheet.
smartsheet.sheets.share(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify share (to one user as Editor).
Share[] shares = new Share[] { new Share.CreateShareBuilder("jane.doe@smartsheet.com", AccessLevel.EDITOR).Build() };

// Share sheet.
smartsheet.SheetResources.ShareResources.ShareTo(sheetId, shares, true);
// Specify share (to one user as Editor).
List<Share> shares = Arrays.asList(new Share.CreateUserShareBuilder().setEmailAddress("jane.doe@smartsheet.com").setAccessLevel(AccessLevel.EDITOR).build());

// Share sheet.
smartsheet.sheetResources().shareResources().shareTo(sheetId, shares, true);

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/{sheetId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'
// Set access level to Viewer.
var share = {"accessLevel": "VIEWER"};

// Set options.
var options = {
    body: share,
    sheetId: 4583614634583940,
    shareId: "AAAFeF82FOeE"
};

// Update sheet share.
smartsheet.sheets.updateShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set access level to Viewer.
Share share = new Share.UpdateShareBuilder(shareId, AccessLevel.VIEWER).Build();

// Update sheet share.
smartsheet.SheetResources.ShareResources.UpdateShare(sheetId, share);
// Set the access level to Viewer.
Share share = new Share.UpdateShareBuilder().setShareId(shareId).setAccessLevel(AccessLevel.VIEWER).build();

// Update report share.
smartsheet.sheetResources().shareResources().updateShare(sheetId, share);

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
// Set options.
var options = {
    workspaceId: 1656220827314052,
    shareId: "AAAEQesWFOeE"
};

// Delete workspace share.
smartsheet.workspaces.deleteShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete workspace share.
smartsheet.WorkspaceResources.ShareResources.DeleteShare(workspaceId, shareId);
// Delete workspace share.
smartsheet.workspaceResources().shareResources().deleteShare(workspaceId, shareId);

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" 
// Set options.
var options = {
    workspaceId: 1656220827314052,
    shareId: "AQAISF82FOeE"
};

// Get workspace share.
smartsheet.workspaces.getShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get workspace share.
smartsheet.WorkspaceResources.ShareResources.GetShare(workspaceId, shareId);
// Get workspace share.
smartsheet.workspaceResources().shareResources().getShare(workspaceId, shareId);

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" 
// Set options.
var options = {
    workspaceId: 1656220827314052
};

// List workspace shares.
smartsheet.workspaces.listShares(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List workspace shares (omit pagination parameters).
smartsheet.WorkspaceResources.ShareResources.ListShares(workspaceId, null);

// List workspace shares (specify 'includeAll' parameter with value of "true").
smartsheet.WorkspaceResources.ShareResources.ListShares(workspaceId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List workspace shares (specify 'includeAll' parameter with value of "true").
smartsheet.workspaceResources().shareResources().listShares(workspaceId, parameters);

// List workspace shares (omit pagination parameters).
smartsheet.workspaceResources().shareResources().listShares(workspaceId, null);

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"}]'
// Specify share (to one user as Editor).
var shares = [
    {
        "email": "john.doe@smartsheet.com",
        "accessLevel": "EDITOR"
    }
];

// Set options.
var options = {
    workspaceId: 7960873114331012,
    body: shares
};

// Share workspace.
smartsheet.workspaces.share(options)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Specify share (to one user as Editor).
Share[] shares = new Share[] { new Share.CreateShareBuilder("jane.doe@smartsheet.com", AccessLevel.EDITOR).Build() };

// Share workspace.
smartsheet.WorkspaceResources.ShareResources.ShareTo(workspaceId, shares, true);
// Specify share (to one user as Editor).
List<Share> shares = Arrays.asList(new Share.CreateUserShareBuilder().setEmailAddress("jane.doe@smartsheet.com").setAccessLevel(AccessLevel.EDITOR).build());

// Share workspace.
smartsheet.workspaceResources().shareResources().shareTo(workspaceId, shares, true);

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"}'
// Set access level to Viewer.
var share = {"accessLevel": "VIEWER"};

// Set options.
var options = {
    body: share,
    workspaceId: 1656220827314052,
    shareId: "AAAFeF82FOeE"
};

// Update workspace share.
smartsheet.workspaces.updateShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set access level to Viewer.
Share share = new Share.UpdateShareBuilder(shareId, AccessLevel.VIEWER).Build();

// Update workspace share.
smartsheet.WorkspaceResources.ShareResources.UpdateShare(workspaceId, share);
// Set the access level to Viewer.
Share share = new Share.UpdateShareBuilder().setShareId(shareId).setAccessLevel(AccessLevel.VIEWER).build();

// Update workspace share.
smartsheet.workspaceResources().shareResources().updateShare(workspaceId, share);

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.
owner string Email address of the Sheet owner
ownerId number User ID of the Sheet owner
permalink string URL that represents a direct link to the Sheet in Smartsheet
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 If true, a lightweight version of the sheet is published without row attachments or discussions.
readOnlyFullEnabled boolean If true, a rich version of the sheet is published with the ability to download row attachments and discussions.
readWriteEnabled boolean If true, a rich version of the sheet is published with the ability to edit cells and manage attachments and discussions.
icalEnabled boolean If true, a webcal will be available for the calendar in the sheet.
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”

Copy Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/copy?include=all \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ \
    "destinationType": "workspace|folder|home", \
    "destinationId": workspace_or_folder_id, \
    "newName": "newSheetName" \
}' \
-X POST
// Specify destination.
ContainerDestination destination = new ContainerDestination
{
    DestinationId = destinationFolderId,
    DestinationType = DestinationType.FOLDER,
    NewName = "newSheetName"
};

// Copy sheet (omit 'include' parameter).
smartsheet.SheetResources.CopySheet(sheetId, destination, null);

// Copy sheet (specify 'include' parameter with value of "all").
smartsheet.SheetResources.CopySheet(sheetId, destination, new SheetCopyInclusion[] { SheetCopyInclusion.ALL });
// Specify destination.
ContainerDestination destination = new ContainerDestination.AddContainerDestinationBuilder()
        .setDestinationType(DestinationType.FOLDER)
        .setDestinationId(destinationFolderId)
        .setNewName("newSheetName")
        .build();

// Copy sheet (omit 'include' parameter).
smartsheet.sheetResources().copySheet(sheetId, destination, null);

// Copy sheet (specify 'include' parameter with value of "all").
smartsheet.sheetResources().copySheet(sheetId, destination, EnumSet.of(SheetCopyInclusion.ALL));

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": 4583173393803140,
        "name": "newSheetName",
        "accessLevel": "OWNER",
        "permalink": "https://{base_url}?lx=lB0JaOh6AX1wGwqxsQIMaA"
    },
    "message": "SUCCESS"
}

POST /sheets/{sheetId}/copy

Creates a copy of the specified Sheet.

Access Scope CREATE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters include (optional) – comma-separated list of elements to copy:
  • data
  • attachments
  • discussions
  • cellLinks
  • forms
  • all - specify a value of “all” to include everything (data, attachments, discussions, cellLinks, and forms)
Note: Cell history will not be copied, regardless of which include parameter values are specified.
Request Body ContainerDestination object
Returns Result object containing a Sheet object for the newly created Sheet, limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink

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"]}]}'
// Specify sheet properties.
var sheet = {
    "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"
            ]
        }
    ]
};

// Set options.
var options = {
    body: sheet
};

// Create sheet in "Sheets" folder.
smartsheet.sheets.createSheet(options)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Specify properties of the first column.
Column columnA = new Column.CreateSheetColumnBuilder("Favorite", null, ColumnType.CHECKBOX).SetSymbol(Symbol.STAR).Build(), 

// Specify properties of the second column.
Column columnB = new Column.CreateSheetColumnBuilder("Primary Column", true, ColumnType.TEXT_NUMBER).Build(), 

// Specify properties of the third column.
Column columnC = new Column.CreateSheetColumnBuilder("col 3", false, ColumnType.PICKLIST).SetOptions(new string[] { "Not Started", "Started", "Completed" }).Build() };

// Create sheet in "Sheets" folder (specifying the 3 columns to include in the sheet).
smartsheet.SheetResources.CreateSheet(new Sheet.CreateSheetBuilder("newsheet", new Column[] { columnA, columnB, columnC }).Build());
// Specify properties of the first column.
Column columnA = new Column.AddColumnToSheetBuilder().setTitle("Favorite").setType(ColumnType.CHECKBOX).setSymbol(Symbol.STAR).build();

// Specify properties of the second column.
Column columnB = new Column.AddColumnToSheetBuilder().setTitle("Primary Column").setType(ColumnType.TEXT_NUMBER).setPrimary(true).build();

// Specify properties of the third column.
Column columnC = new Column.AddColumnToSheetBuilder().setTitle("col 3").setType(ColumnType.PICKLIST).setOptions(Arrays.asList("Not Started", "Started", "Completed")).setPrimary(false).build();

// Create sheet in "Sheets" folder (specifying the 3 columns to include in the sheet).
Sheet sheet = new Sheet.CreateSheetBuilder().setName("newsheet").setColumns(Arrays.asList(columnA, columnB, columnC)).build();
smartsheet.sheetResources().createSheet(sheet);

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"]}]}'
// Specify sheet properties.
var sheet = {
    "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"
            ]
        }
    ]
};

// Set options.
var options = {
    body: sheet,
    folderId: 3734419270854532
};

// Create sheet in folder.
smartsheet.sheets.createSheetInFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify properties of the first column.
Column columnA = new Column.CreateSheetColumnBuilder("Favorite", null, ColumnType.CHECKBOX).SetSymbol(Symbol.STAR).Build(), 

// Specify properties of the second column.
Column columnB = new Column.CreateSheetColumnBuilder("Primary Column", true, ColumnType.TEXT_NUMBER).Build(), 

// Specify properties of the third column.
Column columnC = new Column.CreateSheetColumnBuilder("col 3", false, ColumnType.PICKLIST).SetOptions(new string[] { "Not Started", "Started", "Completed" }).Build() };

// Create sheet in folder (specifying the 3 columns to include in the sheet).
smartsheet.FolderResources.SheetResources.CreateSheet(folderId, new Sheet.CreateSheetBuilder("newsheet", new Column[] { columnA, columnB, columnC }).Build());
// Specify properties of the first column.
Column columnA = new Column.AddColumnToSheetBuilder().setTitle("Favorite").setType(ColumnType.CHECKBOX).setSymbol(Symbol.STAR).build();

// Specify properties of the second column.
Column columnB = new Column.AddColumnToSheetBuilder().setTitle("Primary Column").setType(ColumnType.TEXT_NUMBER).setPrimary(true).build();

// Specify properties of the third column.
Column columnC = new Column.AddColumnToSheetBuilder().setTitle("col 3").setType(ColumnType.PICKLIST).setOptions(Arrays.asList("Not Started", "Started", "Completed")).setPrimary(false).build();

// Create sheet in folder (specifying the 3 columns to include in the sheet).
Sheet sheet = new Sheet.CreateSheetBuilder().setName("newsheet").setColumns(Arrays.asList(columnA, columnB, columnC)).build();

smartsheet.sheetResources().createSheetInFolder(folderId, sheet);

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"]}]}'
// Specify sheet properties.
var sheet = {
    "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"
            ]
        }
    ]
};

// Set options.
var options = {
    body: sheet,
    workspaceId: 1656220827314052
};

// Create sheet in workspace.
smartsheet.sheets.createSheetInWorkspace(options)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Specify properties of the first column.
Column columnA = new Column.CreateSheetColumnBuilder("Favorite", null, ColumnType.CHECKBOX).SetSymbol(Symbol.STAR).Build(), 

// Specify properties of the second column.
Column columnB = new Column.CreateSheetColumnBuilder("Primary Column", true, ColumnType.TEXT_NUMBER).Build(), 

// Specify properties of the third column.
Column columnC = new Column.CreateSheetColumnBuilder("col 3", false, ColumnType.PICKLIST).SetOptions(new string[] { "Not Started", "Started", "Completed" }).Build() };

// Create sheet in workspace (specifying the 3 columns to include in the sheet).
smartsheet.WorkspaceResources.SheetResources.CreateSheet(workspaceId, new Sheet.CreateSheetBuilder("newsheet", new Column[] { columnA, columnB, columnC }).Build());
// Specify properties of the first column.
Column columnA = new Column.AddColumnToSheetBuilder().setTitle("Favorite").setType(ColumnType.CHECKBOX).setSymbol(Symbol.STAR).build();

// Specify properties of the second column.
Column columnB = new Column.AddColumnToSheetBuilder().setTitle("Primary Column").setType(ColumnType.TEXT_NUMBER).setPrimary(true).build();

// Specify properties of the third column.
Column columnC = new Column.AddColumnToSheetBuilder().setTitle("col 3").setType(ColumnType.PICKLIST).setOptions(Arrays.asList("Not Started", "Started", "Completed")).setPrimary(false).build();

// Create sheet in workspace (specifying the 3 columns to include in the sheet).
Sheet sheet = new Sheet.CreateSheetBuilder().setName("newsheet").setColumns(Arrays.asList(columnA, columnB, columnC)).build();

smartsheet.sheetResources().createSheetInWorkspace(workspaceId, sheet);

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": templateId}'
// Specify the directive.
var sheet = {
    "name": "newsheet",
    "fromId": 7679398137620356
};

// Set options.
var options = {
    body: sheet
};

// Create sheet from template.
smartsheet.sheets.createSheetFromExisting(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify name for the sheet and ID of the template.
Sheet sheet = new Sheet.CreateSheetFromTemplateBuilder("newsheet", templateId).Build();

// Create sheet from template (omit 'include' parameter).
smartsheet.SheetResources.CreateSheetFromTemplate(sheet, null);

// Create sheet from template (including data, attachments, and discussions).
smartsheet.SheetResources.CreateSheetFromTemplate(sheet, new TemplateInclusion[] { TemplateInclusion.DATA, TemplateInclusion.ATTACHMENTS, TemplateInclusion.DISCUSSIONS });
// Specify name for the sheet and ID of the template.
Sheet sheet = new Sheet.CreateFromTemplateOrSheetBuilder().setFromId(templateId).setName("newsheet").build();

// Create sheet from template (omit 'include' parameter).
smartsheet.sheetResources().createSheetFromTemplate(sheet, null);

// Create sheet from template (including data, attachments, and discussions).
smartsheet.sheetResources().createSheetFromTemplate(sheet, EnumSet.of(SheetTemplateInclusion.ATTACHMENTS, SheetTemplateInclusion.DATA, SheetTemplateInclusion.DISCUSSIONS));

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}'
// Specify the directive.
var sheet = {
    "name": "newsheet",
    "fromId": 7679398137620356
};

// Set options.
var options = {
    body: sheet,
    folderId: 3734419270854532
};

// Create sheet from template in the specified folder.
smartsheet.sheets.createSheetFromExisting(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify name for the sheet and ID of the template.
Sheet sheet = new Sheet.CreateSheetFromTemplateBuilder("newsheet", templateId).Build();

// Create sheet from template in the specified folder (omit 'include' parameter).
smartsheet.FolderResources.SheetResources.CreateSheetFromTemplate(folderId, sheet, null);

// Create sheet from template in the specified folder (including data, attachments, and discussions).
smartsheet.FolderResources.SheetResources.CreateSheetFromTemplate(folderId, sheet, new TemplateInclusion[] { TemplateInclusion.DATA, TemplateInclusion.ATTACHMENTS, TemplateInclusion.DISCUSSIONS });
// Specify name for the sheet and ID of the template.
Sheet sheet = new Sheet.CreateFromTemplateOrSheetBuilder().setFromId(templateId).setName("newsheet").build();

// Create sheet from template in the specified folder (omit 'include' parameter).
smartsheet.sheetResources().createSheetInFolderFromTemplate(folderId, sheet, null);

// Create sheet from template (including data, attachments, and discussions).
smartsheet.sheetResources().createSheetInFolderFromTemplate(folderId, sheet, EnumSet.of(SheetTemplateInclusion.ATTACHMENTS, SheetTemplateInclusion.DATA, SheetTemplateInclusion.DISCUSSIONS));  

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}'
// Specify the directive.
var sheet = {
    "name": "newsheet",
    "fromId": 7679398137620356
};

// Set options.
var options = {
    body: sheet,
    workspaceId: 1656220827314052
};

// Create sheet from template in the specified workspace.
smartsheet.sheets.createSheetFromExisting(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify name for the sheet and ID of the template.
Sheet sheet = new Sheet.CreateSheetFromTemplateBuilder("newsheet", templateId).Build();

// Create sheet from template in the specified workspace (omit 'include' parameter).
smartsheet.WorkspaceResources.SheetResources.CreateSheetFromTemplate(workspaceId, sheet, null);

// Create sheet from template in the specified workspace (including data, attachments, and discussions).
smartsheet.WorkspaceResources.SheetResources.CreateSheetFromTemplate(workspaceId, sheet, new TemplateInclusion[] { TemplateInclusion.DATA, TemplateInclusion.ATTACHMENTS, TemplateInclusion.DISCUSSIONS });
// Specify name for the sheet and ID of the template.
Sheet sheet = new Sheet.CreateFromTemplateOrSheetBuilder().setFromId(templateId).setName("newsheet").build();

// Create sheet from template in the specified folder (omit 'include' parameter).
smartsheet.sheetResources().createSheetInFolderFromTemplate(folderId, sheet, null);

// Create sheet from template in the specified workspace (including data, attachments, and discussions).
smartsheet.sheetResources().createSheetInWorkspaceFromTemplate(folderId, sheet, EnumSet.of(SheetTemplateInclusion.ATTACHMENTS, SheetTemplateInclusion.DATA, SheetTemplateInclusion.DISCUSSIONS));   

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
// Set options.
var options = {
    id: 1531988831168388 // ID of Sheet
};

// Delete sheet.
smartsheet.sheets.deleteSheet(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete sheet.
smartsheet.SheetResources.DeleteSheet(sheetId);
// Delete sheet.
smartsheet.sheetResources().deleteSheet(sheetId);

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"
// Set options.
var options = {
    sheetId: 1531988831168388
};

// Get sheet version.
smartsheet.sheets.getSheetVersion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get sheet version.
smartsheet.SheetResources.GetSheetVersion(sheetId);
// Get sheet version.
smartsheet.sheetResources().getSheetVersion(sheetId);

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"
// Set options.
var options = {
    id: 4583173393803140 // ID of Sheet
};

// Get sheet.
smartsheet.sheets.getSheet(options)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Get sheet (omit all parameters).
smartsheet.SheetResources.GetSheet(sheetId, null, null, null, null, null, null, null);
// Get sheet (omit all parameters).
smartsheet.sheetResources().getSheet(sheetId, null, null, null, null, null, null, null);

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 elements 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
  • ownerInfo: includes owner’s email address and user ID
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 (Excel):

curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/vnd.ms-excel" \
-o output.xls
// Set options.
var options = {
  id: 4583173393803140 // ID of Sheet
};

// Get sheet as Excel.
smartsheet.sheets.getSheetAsExcel(options)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Get sheet as Excel.
smartsheet.SheetResources.GetSheetAsExcel(sheetId, outputStream);
// Get sheet as Excel.
smartsheet.sheetResources().getSheetAsExcel(sheetId, outputStream);

Example Response:

# See local file named "output.xls"
// [todo]
// Contents of Excel file will be written to "outputStream"
// Contents of Excel file will be written to "outputStream"

Example Request (PDF):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}?paperSize=A1 \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/pdf" 
-o  output.pdf
// Set options.
var options = {
  id: 4583173393803140 // ID of Sheet
};

// Get sheet as PDF.
smartsheet.sheets.getSheetAsPDF(options)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Get sheet as PDF.
smartsheet.SheetResources.GetSheetAsPDF(sheetId, outputStream, PaperSize.A1);
// Get sheet as PDF.
smartsheet.sheetResources().getSheetAsPDF(sheetId, outputStream, PaperSize.A1);

Example Response:

# See local file named "output.pdf"
// [todo]
// Contents of PDF file will be written to "outputStream"
// Contents of PDF file will be written to "outputStream"

Example Request (CSV):

curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: text/csv" \
-o output.csv
// Set options.
var options = {
  id: 4583173393803140 // ID of Sheet
};

// Get sheet as CSV.
smartsheet.sheets.getSheetAsCSV(options)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Get sheet as CSV.
smartsheet.SheetResources.GetSheetAsCSV(sheetId, outputStream);
// Get sheet as CSV.
smartsheet.sheetResources().getSheetAsCSV(sheetId, outputStream);

Example Response:

# See local file named "output.csv"
// [todo]
// Contents of CSV file will be written to "outputStream"
// Contents of CSV file will be written to "outputStream"

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"
// List all org sheets.
smartsheet.sheets.listOrganizationSheets()
    .then(function(data) {
        console.log(data)
    })
    .catch(function(error) {
        console.log(error);
    });
// List all org sheets.
smartsheet.UserResources.SheetResources.ListSheets();
// List all org sheets.
smartsheet.userResources().listOrgSheets();

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"
// List sheets.
smartsheet.sheets.listSheets()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// List sheets (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.ListSheets(null, null);

// List sheets (specify 'include' parameter with value of "source", and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.ListSheets(new SheetInclusion[] { SheetInclusion.SOURCE }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List sheets (specify 'include' parameter with value of "source", and 'includeAll' parameter with value of "true").
smartsheet.sheetResources().listSheets(EnumSet.of(SourceInclusion.SOURCE), parameters);

// List sheets (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().listSheets(null, null);

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",
            "createdAt": "2015-06-05T20:05:29Z",
            "modifiedAt": "2015-06-05T20:05:43Z"
        },
        {
            "accessLevel": "OWNER",
            "id": 2331373580117892,