Smartsheet Developers

API Documentation

_____________________________

API Fundamentals

Overview

Rate Limiting

Errors

Authentication

Access Levels

About Columns

Column Types

Strict vs. Lenient Parsing

Contact List Columns

System Columns

Developer Account

SDKs and sample code

Direct API Access

Generating Access Token

Using Access Tokens

Third Party App Development

Developer Registration

Registering Your App

Access Scopes

OAuth Flow

Admin Features

Manage Users

Assume-User

Maintain Data Attribution

List All Org Sheets

Backup All Org Data

Home

Home Object

List All Contents

List Folders

Create Folder

Favorites

Favorite Object

List All Favorites

Create Favorites

Delete Favorite

Delete Favorites in Bulk

Workspaces

Workspace Object

List All Workspaces

Get Workspace

Create Workspace

Update Workspace

Delete Workspace

List Folders

Create Folder

Create Sheet

Share Workspace

Folders

Folder Object

Get Folder

Update Folder

Delete Folder

List Child Folders

Create Child Folder

Create Sheet

Templates

Template Object

List All Templates

Sheets

Sheet Object

List All Sheets

Get Sheet (incl. Rows)

Get as Excel/PDF/CSV

Create Sheet

Create from Sheet or Template

Delete Sheet

Update Sheet

Get Sheet Version

Send Sheet

Search Sheet

Share Sheet

Sheet Columns

Get Columns

Add Column to Sheet

Sheet Rows

RowWrapper Object

Insert Rows into Sheet

Get Row by Number

Sheet Attachments

Get Sheet Attachments

Attach File

Attach URL

Sheet Discussions

Sheet Publishing

Sheet Publish Object

Get Publish Status

Set Publish Status

Reports

Report Object

Report Column Object

Report Row Object

Report Cell Object

Get Report

Send Report

Share Report

Columns

Column Object

Filter Object

Criteria Object

Modify Column

Delete Column

Rows

Row Object

Get Row

Modify Row

Delete Row

Send Row

Row Cells

Cell Object

Cell History Object

Creating and Updating Links

Hyperlinks

Cell Links

Update Row Cells

Get Cell History

Row Attachments

Get Row Attachments

Attach File

Attach URL

Row Discussions

Attachments

Attachment Object

Get Attachment

Posting an Attachment

Attach File

Attach URL

Delete Attachment

Attachment Versions

Get All Versions

Upload New Version

Delete All Versions

Discussions

Discussion Object

Get Discussion

Create Discussion

Delete Discussion

Add Comment

Get Discussion Attachments

Comments

Comment Object

Get Comment

Delete Comment

Attach File

Attach URL

Users

User Object

User Profile Object

List All Users

Add User

Get Current User

Get User

Update User

Delete User

List All Sheets

Groups

Group Object

Group Member Object

List All Groups

Get Group

Create Group

Update Group

Delete Group

Group Members

Add Members to Group

Remove Memeber From Group

Search

Search Result Object

SearchResultItem Object

Search Everything

Search Sheet

Sharing

Share Object

MultiShare Object

Get Shares

Get Share

Share to One

Share to Many

Update Share

Delete Share

Sharing with Groups

ShareWithGroups Object

MultiShareWithGroups Object

Get Shares (with Groups)

Get Share (with Groups)

Share (with Groups) to One

Share (with Groups) to Many

Update Share (with Groups)

Delete Share (with Groups)

Server Information

ServerInfo Object

Get Server Info

Formatting

Row & Column Format

Format Descriptor

FormatTables Object

FontFamily Object

Currency Object

Other Objects

Result Object

Email Object

RowEmail Object

SheetEmail Object

Link Object

Hyperlink Object

CellLink Object

AutoNumberFormat Object

API Fundamentals

Overview

___________________________________________________________________________

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

Everything in Smartsheet is represented as an object with a defined structure. Whether it is a "Home" object that represents your list of Sheets and Workspaces, or a Sheet object with "Row" and "Column" objects, or a list of "Shares" that indicate who has access to a given sheet, 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 HTTP GET to https://api.smartsheet.com/1.1/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 to https://api.smartsheet.com/1.1/sheet/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/1.1/sheet/123456/shares.

HTTP Methods and Response Codes

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

Request body data is expected to be in JSON, and the response body data is returned as JSON.  Note: some of the data returned by the Smartsheet API is user-generated content. Caution should be taken to ensure that the user-generated content is consumed safely in any external system to avoid introducing vulnerabilities. 

Example Requests and Responses

With every API method we provide a sample request and a sample response.  The requests shown use a command line data transfer tool cURL.  Alternatively, you can use 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.

If new functionality is added to the API, we will let you know via our Developer Portal and other means of communication, such as Twitter, Facebook or email. Please follow these sources to stay up to date on the latest changes.

Help

Email us directly at api@smartsheet.com with any questions or suggestions.

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/1.1/sheet/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 less than {1} 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

The column specified is either a calendar, Gantt, or dependency column and the type cannot be changed.

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.

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.

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

About Columns

Column Types

Smartsheet has 5 basic column types: Text/Number, Contact List, Date, Dropdown List (custom, RYG, Harvey Ball, and Priority types) and Checkbox (checkbox, star, and flag types). These types are referred to as  the following constant values in the API: TEXT_NUMBER, CONTACT_LIST, DATE, PICKLIST, and CHECKBOX.

In addition to the column types, there are symbols available within Smartsheet. These are simply specialized PICKLIST or CHECKBOX types. The available CHECKBOX symbols are FLAG and STAR. The available PICKLIST symbols are HARVEY_BALLS, RYG, and PRIORITY.

Strict vs. Lenient Parsing

Within the Smartsheet web application, the column types are flexible and generally, any column can contain any type of data. This allows for a very flexible UI and is one of the key benefits to using Smartsheet. This flexibility, however, poses a challenge for an API. 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, Smartsheet has employed 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. 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. The rules 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.

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 it’s an empty string, the Smartsheet cell will display the email address.
  • If it’s null or absent, Smartsheet will make a best guess effort at filling it in with a contact’s name based on the email address.

System Columns

In addition to the standard column types and symbols, there are system columns - columns whose values cannot be changed by the user. These include the following systemColumnType values:

MODIFIED_DATE                 (type DATETIME)

MODIFIED_BY                 (type CONTACT_LIST)

CREATED_DATE                 (type DATETIME)

CREATED_BY                (type CONTACT_LIST)

AUTO_NUMBER                 (type TEXT_NUMBER)

When a column is of this systemColumnType, it will include an AutoNumberFormat object that describes the mask used to generate the value.

Developer Account

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

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

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

SDKs and sample code

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

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

Direct API Access

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

Generating Access Token

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

  1. Click on the Account button in the upper left hand 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 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.

IMPORTANT: Note that you will have only one opportunity to view and copy your newly generated token.  For security reasons, you will not be able to retrieve it at a later time.  If you lose your token, however, it is easy to use the UI to revoke it and generate a new one.

IMPORTANT: Access Tokens are essentially passwords and grant the holder access to all of your Smartsheet data.  It is imperative that you keep them secure.

Using Access Tokens

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

Authorization: Bearer 0da6cf0d848266b4cd32a6151b1f

Note that 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.

As the first step in working with the API, it may be useful to confirm who you are.  You can do that using the /user/me call:

curl https://api.smartsheet.com/1.1/user/me \

-H "Authorization: Bearer ACCESS_TOKEN"

You should get back a user object with your user ID, name and email address:

{

    "email": "john.doe@smartsheet.com",

    "firstName": "John",

    "lastName": "Doe",

    "id": 48569348493401200

}

To access your Sheet list, construct an HTTPS request using your favorite programming or scripting language. Here is an example using the cURL tool from a Linux command line:

curl https://api.smartsheet.com/1.1/sheets \

-H "Authorization: Bearer ACCESS_TOKEN"

The resulting JSON will look something like this:

[{

   "id": 5392413951846276,

   "name": "Bug List",

   "accessLevel": "OWNER"

 },

 {

   "id": 3175798510249860,

   "name": "My Task List",

   "accessLevel": "EDITOR"

 },

 {

   "id": 5146123347224452,

   "name": "API Integration Project Plan",

   "accessLevel": "OWNER"

}]

Use your favorite JSON parser to consume the output. Once you have parsed the data, you can make your next request to fetch sheet data. The following cURL request will fetch the sheet data for the "Bug List" sheet from above:

curl https://api.smartsheet.com/1.1/sheet/5392413951846276 \

-H "Authorization: Bearer ACCESS_TOKEN"

The resulting JSON will look something like this:

{  

   "id": 5392413951846276,

   "name": "Bug List",

   "columns": [

      {

         "id": 8774511718885252,

         "index": 0,

         "title": "Title",

         "type": "TEXT"

},

      {

         "id": 6944924370265988,

         "index": 4,

         "title": "Version Found",

         "type": "PICKLIST",

         "options": [

            "9.0.0 "8.0.4","8.0.3","8.0.2",

            "8.0.1","8.0.0","8.0.0 RC1"

         ]

                },

// ....

],

   "rows": [

      {

         "id": 5337309521438596,

         "rowNumber": 1,

         "cells": [

         {

            "type": "TEXT_NUMBER",

            "id": 687492027443076,

            "value": "Unable to see DIV in Internet Explorer 7 and lower",

            "columnId": 8774511718885252

         },

         {

            "type": "PICKLIST",

            "id": 1813391934285700,

            "value": "9.0.0 RC1",

            "columnId": 6944924370265988

         }

         // ...

         ]

},

      // ...

   ]

}

To perform a PUT, e.g. to modify a sheet share, or a POST, e.g. to insert a row, construct the JSON object and include it in the HTTP request body.  Be sure to also set the Content-Type header to "application/json". To create a discussion via a POST, use the following curl request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/discussions \

-H "Authorization: Bearer ACESS_TOKEN" \

-H "Content-Type: application/json" \

-d '{"title" : "My New Discussion","comment":{"text":"My first comment"} }'

-X POST

You are now ready to build your own Smartsheet API integration!

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 will be building applications that allow any Smartsheet user to access his or her Smartsheet data.  Your app must implement a 3-legged OAuth flow to redirect your end users to Smartsheet for authentication and app authorization.

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 on the Account button in the upper left hand 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. Open your Developer Tools (Account > Developer Tools).
  2. 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.
  3. 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

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

Note: third party apps should only request the scopes necessary. User-generated Access Tokens are granted all of these permissions.

OAuth Flow

Requesting an authorization code

After completing your Developer Profile and registering your new App, your app will need an Access Token to access Smartsheet on behalf of an end user.  To do so, first direct your user to https://www.smartsheet.com/b/authorize with the following parameters through either a GET or POST. The parameter values must be URL-encoded:

response_type (required)

must be set to "code"

client_id (required)

client id for your app

redirect_uri (required)

redirect URL you registered for your app (including protocol, e.g. "http://")

scope (required)

space-delimited list of access scopes to which you are asking the user to grant access (note the spaces must be URL-encoded as "%20")

state

arbitrary string that will be returned to your app; intended to be used by you to ensure that this redirect is indeed from an OAuth flow that you initiated.

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

https://www.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&redirect_uri=https%3A%2F%2Fmyapp.smartsheet.com%2Ftarget&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 your 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

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/1.1/token with the following parameters (all parameters are required):

grant_type

must be set to "authorization_code"

client_id

client id for your app

code

authorization code returned in the previous step

redirect_uri

redirect URL registered for your app, including the protocol (e.g., "http://")

hash

SHA-256 hash of your client secret concatenated with a pipe and the authorization code.  The client_secret is never sent with the request.

Here’s how you would build your hash using Java:

String doHash = clientSecret + "|" + code;

MessageDigest md = MessageDigest.getInstance("SHA-256");

byte[] digest = md.digest(doHash.getBytes("UTF-8"));

String hex = Hex.encodeHexString(digest);

Note that, unlike the rest of the API, this request is made with a Content-Type of 'application/x-www-form-urlencoded' and not 'application/json'.   Here’s an example request using cURL:

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

If all goes well, you will receive a 200 response with a JSON body like this:

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

Otherwise, if an error occurs, the JSON body will look like this:

{

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

Possible OAuth error types:

invalid_request

The request parameters are invalid or missing.

invalid_client

The client information is invalid. Ensure your client id is correct.

invalid_grant

The authorization code or refresh token is invalid or expired, the redirect_uri does not match, or the hash value does not match the client secret and/or code.

unsupported_grant_type

grant_type must equal “authorization_code” or “refresh_token”.

Refreshing access token

An access token is valid for one week but you can use the refresh token to obtain a new access token.

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

grant_type

must be set to "refresh_token"

client_id

client id for your app

refresh_token

refresh_token value that came with the access token

redirect_uri

redirect URL registered for your app, including the protocol (e.g., "http://")

hash

SHA-256 hash of your client secret concatenated with a pipe and the refresh token value

Note that, again, this request is must have the Content-Type set to 'application/x-www-form-urlencoded'.  Here is an example request using cURL:

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

If all goes well, you will receive a JSON response with a new access token like this:

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

You will then be able to use the new access token in place of the old one, which is no longer valid.

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 /user/me operation.

Admin Features

Smartsheet Administrators have access to additional API features, including user management and ability to access any sheet in the organization.

Manage Users

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

Assume-User

As an 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.

Base URL

https://api.smartsheet.com/1.1

Resources:

/home

/favorites

/workspaces

/folders

/templates

/sheets

/reports

/columns

/rows

/attachments

/discussions

/comments

/users

/groups

/search

/serverinfo

API Quick Reference

Maintain Data Attribution

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?  Assume-User allows org Administrators to develop integrations which do just that:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/rows \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Assume-User: bob.johnson%40smartsheet.com" \

-H "Content-Type: application/json" \

-X POST \

-d '{"toTop":true", "rows":[{"cells": [ {"columnId": 3738748463671172, "value": "Revision 1"}, {"columnId": 5427598323935108, "value": "New status", "strict": false} ]} ]}'

List All Org 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 Users > List All Sheets for more information.

Backup All Org Data

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

Get a list of all sheets in your organization:

curl https://api.smartsheet.com/1.1/users/sheets \

-H "Authorization: Bearer ACCESS_TOKEN"

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:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}?include=discussions,attachments \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Assume-User: OWNER_EMAIL"

where OWNER_EMAIL is a URI-encoded email address of the sheet owner.

You can also backup all the files attached to the sheet, by fetching them one at a time, using your favorite file download method.  For example, with cURL you would do something like this:

curl -0 URL_TO_ATTACHMENT

where URL_TO_ATTACHMENT is a temporary URL generated by Smartsheet.  See Attachments > Get Attachment for more information.

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

API Reference

Home

Home Object

sheets

array

array of Sheet objects

folders

array

array of Folder objects

reports

array

array of Report objects

templates

array

array of Template objects

workspaces

array

array of Workspace objects

Methods

List All Contents

Provides a nested list of all Home objects, including sheets, workspaces and folders, and optionally reports and/or templates, as shown on the Home tab.

NOTE: if there are no folders, sheets, templates (optional), or workspaces present, empty arrays are returned.

Method

GET /home

Access Scope

READ_SHEETS

Parameters

    include

    (optional)

value must be "templates"

Returns

Home object, populated according to the "include" parameter.

Example request:

curl https://api.smartsheet.com/1.1/home?include=templates \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "folders": [

        {

            "id": 5709073300645764,

            "name": "folder 1"

        }

    ],

    "sheets": [

        {

            "accessLevel": "OWNER",

            "id": 4583173393803140,

            "name": "sheet 1"

        },

        {

            "accessLevel": "OWNER",

            "id": 2331373580117892,

            "name": "sheet 2"

        }

    ],

    "templates": [],

    "workspaces": []

}

List Folders

Returns an array of folders.

See Folders > List Child Folders for details.

Create Folder

Creates folder.

See Folders > Create Child Folder for details.

Favorites

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

Favorite Object

type

string

One of:

  • workspace
  • folder
  • sheet
  • report

objectId

number

ID of the favorite object.

Methods

List All Favorites

Lists all of the current user's favorite items.

Method

GET /favorites

Access Scope

READ_SHEETS

Returns

Array of Favorite objects.

Example request:

curl https://api.smartsheet.com/1.1/favorites \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "type": "sheet",

        "objectId": 5897312590423940

    },

    {

        "type": "folder",

        "objectId": 1493728255862660

    }

]

Create Favorites

Marks objects as a favorites.

Method

POST /favorites

Access Scope

ADMIN_WORKSPACES

Request Body

Array of Favorite objects with "type" and "objectId" set.

Returns

Array of favorites that were created.  If any of the objects in the request were already favorites, they will be skipped and omitted from the response.

Example request:

curl https://api.smartsheet.com/1.1/favorites \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '[{"type": "sheet", "objectId": 8400677765441412}]'

Example response:

{

    "resultCode": 0,

    "result": [

        {

            "type": "sheet",

            "objectId": 8400677765441412

        }

    ],

    "message": "SUCCESS"

}

Delete Favorite

Unmarks an object as a favorite.

Method

DELETE /favorites/{type}/{objectId}

type is one of "workspace", "folder", "sheet", or "report"

Access Scope

ADMIN_WORKSPACES

Returns

Result object indicating success

Example request:

curl https://api.smartsheet.com/1.1/favorites/sheet/{sheetId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Delete Favorites in Bulk

Unmarks multiple objects of a given type in bulk

Method

DELETE /favorites/{type}?objectIds={objectIds}

type is one of "workspace", "folder", "sheet", or "report"

objectIds is a comma-separated list of object IDs

Access Scope

ADMIN_WORKSPACES

Returns

Result object indicating success

Example request:

curl https://api.smartsheet.com/1.1/favorites/sheet?objectIds={sheetId1},{sheetId2} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Workspaces

Workspace Object

id

number

workspace ID

name

string

workspace name

favorite

boolean, "true"

returned only if this user has marked this workspace as a favorite in their home tab.

accessLevel

string

user's permissions on workspace

permalink

string

direct URL to workspace

sheets

array

array of Sheet objects

folders

array

array of Folder objects

Methods

List All Workspaces

Lists all of the Workspaces to which the user has access.

Method

GET /workspaces

Access Scope

READ_SHEETS

Returns

Array of Workspace objects.

Example request:

curl https://api.smartsheet.com/1.1/workspaces \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "accessLevel": "OWNER",

        "id": 3457273486960516,

        "name": "workspace 1",

        "permalink": "https://www.smartsheet.com/b/home?lx=JNL0bgXtXc0pzni9tzAc4g"

    },

    {

        "accessLevel": "OWNER",

        "id": 7960873114331012,

        "name": "workspace 2",

        "permalink": "https://www.smartsheet.com/b/home?lx=JLiJbgXtXc0pzni9tzAKiR"

    }

]

Get Workspace

Lists contents of a Workspace. By default, this only lists the top level items in the workspace. To load all of the contents, including nested folders, include the "loadAll=true" query string parameter.

NOTE: if no folders and/or sheets are present in the workspace, the corresponding attribute (e.g., "folders", "sheets") will not be present in the response object.

Method

GET /workspace/{workspaceid}

Access Scope

READ_SHEETS

Parameters

   loadAll (optional)

true/false (default)

Returns

Workspace object.

Example request:

curl https://api.smartsheet.com/1.1/workspace/{workspaceid} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "sheets": [

       {

            "accessLevel": "OWNER",

            "id": 4583173393803140,

            "name": "sheet 1"

        }

],

    "accessLevel": "OWNER",

    "id": 7116448184199044,

    "name": "New workspace",

    "permalink": "https://smartsheet.com/home?lx=8Z0XuFUEAkxmHCSsMw4Zgg"

}

Create Workspace

Creates a new Workspace.

Method

POST /workspaces

Access Scope

ADMIN_WORKSPACES

Headers

Content-Type: application/json

Request Body

Workspace object limited to the following attribute:

  • name (string)

Returns

Result object containing the newly created Workspace object.

Example request:

curl https://api.smartsheet.com/1.1/workspaces \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"name": "New workspace"}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "accessLevel": "OWNER",

        "id": 7960873114331012,

        "name": "New workspace",

        "permalink": "https://smartsheet.com/home?lx=rBU8QqUVPCJ3geRgl7L8yQ"

    },

    "resultCode": 0

}

Update Workspace

Updates a Workspace.

Method

PUT /workspace/{id}

Access Scope

ADMIN_WORKSPACES

Headers

Content-Type: application/json

Request Body

Workspace object limited to the following attribute:

  • name (string)

Returns

Result object containing the updated Workspace object.

Example request:

curl https://api.smartsheet.com/1.1/workspace/7960873114331012 \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{"name": "Updated workspace"}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "accessLevel": "OWNER",

        "id": 7960873114331012,

        "name": "Updated workspace",

        "permalink": "https://smartsheet.com/home?lx=rBU8QqUVPCJ3geRgl7L8yQ"

    },

    "resultCode": 0

}

Delete Workspace

Deletes a Workspace and all its contents.

Method

DELETE /workspace/{id}

Access Scope

ADMIN_WORKSPACES

Returns

Result object indicating success..

Example request:

curl https://api.smartsheet.com/1.1/workspace/7960873114331012 \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

List Folders

List all folders in the workspace.

See Folders > List Child Folders for details.

Create Folder

Creates folder into the workspace.

See Folders > Create Child Folder for details.

Create Sheet

Creates sheet into the workspace.

See Sheets > Create Sheet for details.

Share Workspace

See Sharing.

Folders

Folder Object

id

number

the id of the object

name

string

the name of the folder

favorite

boolean, "true"

returned only if this user has marked this folder as a favorite in their home tab.

permalink

string

direct URL to folder

sheets

array

array of Sheet objects

folders

array

array of Folder objects

reports

array

array of Report objects

templates

array

array of Template objects

workspaces

array

array of Workspace objects

Get Folder

List contents of a Folder.

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

Method

GET /folder/{folderId}

Access Scope

READ_SHEETS

Returns

Folder object.

Example request:

curl https://api.smartsheet.com/1.1/folder/{folderId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "id": 7116448184199044,

    "name": "New folder"

}

Update Folder

Updates folder.

Method

PUT /folder/{folderId}

Access Scope

ADMIN_WORKSPACES

Headers

Content-type: application/json

Request Body

JSON-formatted Sheet object, limited to the following required attributes:

  • name (string)

Name need not be unique.

Returns

Result object containing updated Folder object.

Example request:

curl https://api.smartsheet.com/1.1/folder/{folderId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{"name": "New name for folder"}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "id": 1486948649985924,

        "name": "New name for folder"

    },

    "resultCode": 0

}

Delete Folder

Deletes folder and its contents.

Method

DELETE /folder/{folderId}

Access Scope

ADMIN_WORKSPACES

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/folder/{folderId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "resultCode": 0,

    "message": "SUCCESS"

}

List Child Folders

Returns an array of top-level child folders.

Method

GET /home/folders

GET /workspace/{workspaceId}/folders

GET /folder/{folderId}/folders

Access Scope

READ_SHEETS

Returns

Array of Folder objects, limited to the following attributes:

  • id
  • name

Example request:

curl https://api.smartsheet.com/1.1/home/folders \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json"

Example response:

[

  {

    "id": 7116448184199044,

    "name": "New folder"

  },

  ...

]

Create Child Folder

Creates child folder.

Method

POST /home/folders

POST /workspace/{workspaceId}/folders

POST /folder/{folderId}/folders

Access Scope

ADMIN_WORKSPACES

Headers

Content-type: application/json

Request Body

JSON-formatted Sheet object, limited to the following required attributes:

  • name (string)

Name need not be unique.

Returns

Result object containing Folder object, limited to the following attributes:

  • id
  • name

Example request:

curl https://api.smartsheet.com/1.1/home/folders \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"name": "New folder"}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "id": 1486948649985924,

        "name": "New folder"

    },

    "resultCode": 0

}

Create Sheet

Creates sheet into folder.

See Sheets > Create Sheet for details.

Templates

Template Object

id

number

template ID

name

string

template name

description

string

template description

accessLevel

string

user's permissions on template

Methods

List All Templates

Lists all of the templates to which the user has access.

Note: only user-created templates will be returned.  If you like a public template created by Smartsheet and want to make it available via the API, please save it as your own template.

Method

GET /templates

Access Scope

READ_SHEETS

Returns

Array of Template objects

Example request:

curl https://api.smartsheet.com/1.1/templates \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "id": 3457273486960516,

        "name": "template 1",

        "accessLevel": "OWNER",

        "description": "This is template 1"

    }

]

Sheets

Sheet Object

id

number

sheet ID

name

string

sheet name

columns

array

array of Column objects

rows

array

array of Row objects

accessLevel

string

user's permissions on sheet

discussions

array

array of Discussion objects

attachments

array

array of Attachment objects

effectiveAttachmentOptions

array

array of enum strings (see Attachment.attachmentType) indicating the allowable attachment options for the current user and sheet.

readOnly

boolean, "true"

returned only if sheet belongs to expired trial

createdAt

timestamp

time sheet was created

modifiedAt

timestamp

time sheet was modified

permalink

string

direct URL to sheet

ganttEnabled

boolean

a flag to indicate that gantt is enabled.

dependenciesEnabled

boolean

a flag to indicate that dependencies are enabled.

favorite

boolean, "true"

returned only if this user has marked this sheet as a favorite in their home tab.

showParentRowsForFilters

boolean, "true"

returned only if there are column filters on the sheet, and "show parent rows" is enabled

version

number

an number that is incremented every time a sheet is modified.

totalRowCount

number

The total number of rows in the sheet

Methods

List All Sheets

Lists all the sheets in alphabetical order, by name

Method

GET /sheets

Access Scope

READ_SHEETS

Returns

Array of Sheet objects, limited to the following attributes:

  • id
  • name
  • accessLevel

Example request:

curl https://api.smartsheet.com/1.1/sheets \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "accessLevel": "OWNER",

        "id": 4583173393803140,

        "name": "sheet 1"

    },

    {

        "accessLevel": "OWNER",

        "id": 2331373580117892,

        "name": "sheet 2"

    }

]

Get Sheet (incl. Rows)

Returns the sheet, including Rows, and optionally populated with Discussion and Attachment objects.

Method

GET /sheet/{sheetId}

Access Scope

READ_SHEETS

Parameters

include

(optional)

Comma-separated list of optional objects to include in the response:

  • discussions
  • attachments
  • format
  • filters

To include discussion attachments, both attachments and discussions parameters must be present in the query string.

rowIds

(optional)

Comma-separated list of row IDs on which to filter the rows included in the result.

columnIds

(optional)

Comma-separated list of column IDs .  The response payload 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.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "accessLevel": "OWNER",

    "columns": [

        {

            "id": 4583173393803140,

            "index": 0,

            "primary": true,

            "title": "Primary Column",

            "type": "TEXT_NUMBER"

        },

        {

            "id": 2331373580117892,

            "index": 1,

            "options": [

                "new",

                "in progress",

                "completed"

            ],

            "title": "status",

            "type": "PICKLIST"

        }

    ],

    "createdAt": "2012-07-24T18:22:29-07:00",

    "id": 4583173393803140,

    "modifiedAt": "2012-07-24T18:30:52-07:00",

    "name": "sheet 1",

    "permalink": "https://smartsheet.com/home?lx=pWNSDH9itjBXxBzFmyf-5w",

    "rows": []

}

Get as Excel/PDF/CSV

Returns the sheet in the format specified.  Gantt chart is not generated at this time.

Method

GET /sheet/{sheetId}

Access Scope

READ_SHEETS

Parameters

    paperSize (optional)

query string parameter, applies to PDF only, must be one of:

LETTER (default)

LEGAL

WIDE (Same as 11x17)

ARCHD

A4

A3

A2

A1

A0

Header

    Accept

   

Must be one of the following:

  • application/pdf
  • application/vnd.ms-excel
  • text/csv

Returns

The file in either Excel or PDF format.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}?paperSize=A1 \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Accept: application/pdf" -o  output.pdf

Note: for Excel format, only .xls output format is supported at this time.

Example Response:

See local file named "output.pdf"

Create Sheet

Creates a sheet from scratch. Sheets can be created in your default "Sheets" collection, into a workspace or into any folder whether that folder is in a shared workspace or your personal "Sheets" collection. See "Method" below for the URL to use for each of these operations.

Method

POST /sheets

POST /folder/{folderId}/sheets

POST /workspace/{workspaceId}/sheets

Access Scope

CREATE_SHEETS

Headers

Content-type: application/json

Request Body

JSON-formatted Sheet object, limited to the following required attributes:

  • name (string)
  • columns (array of Column objects, limited to the following attributes)
  • title
  • primary
  • type
  • symbol (optional)
  • options (optional)
  • systemColumnType (optional)
  • autoNumberFormat (optional)
  • width (optional)

NOTE:

Name need not be unique.  Column titles must be unique within the sheet.

Only one column may be designated as primary.

Returns

Result object, containing a Sheet object for the newly created sheet, limited to the following attributes:

  • id
  • name
  • accessLevel
  • permalink
  • columns

Example request:

curl https://api.smartsheet.com/1.1/sheets \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"name":"newsheet","columns":[{"title":"Favorite","type":"CHECKBOX","symbol":"STAR"}, {"title":"Primary Column", "primary":true,"type":"TEXT_NUMBER"}, {"title":"Status", "type":"PICKLIST", "options":["Not Started","Started","Completed"]}]}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "accessLevel": "OWNER",

        "columns": [

            {

                "id": 7960873114331012,

                "index": 0,

                "symbol": "STAR",

                "title": "Favorite",

                "type": "CHECKBOX"

            },

            {

                "id": 642523719853956,

                "index": 1,

                "primary": true,

                "title": "Primary Column",

                "type": "TEXT_NUMBER"

            },

            {

                "id": 5146123347224452,

                "index": 2,

                "options": [

                    "Not Started",

                    "Started",

                    "Completed"

                ],

                "title": "Status",

                "type": "PICKLIST"

            }

        ],

        "id": 2331373580117892,

        "name": "newsheet",

        "permalink": "https://smartsheet.com/home?lx=0HHzeGnfHik-N13ZT8pU7g"

    },

    "resultCode": 0

}

Create from Sheet or Template

Creates a sheet from an existing sheet or template. Sheets can be created in your default "Sheets" collection, into a workspace or into any folder whether that folder is in a shared workspace or your personal "Sheets" collection. See "Method" below for the URL to use for each of these operations.

Method

POST /sheets

POST /folder/{folderId}/sheets

POST /workspace/{workspaceId}/sheets

Access Scope

CREATE_SHEETS

Headers

Content-type: application/json

Request Body

JSON-formatted Sheet object, limited to the following attributes:

  • name (string)
  • fromId (number): ID of the Sheet or Template from which to create the sheet.

Name need not be unique.

Parameters

    include

    (optional)

Comma separated list of the following optional elements to be copied from the template to the sheet :

data

attachments

discussions

cellLinks

forms

Returns

Result object containing a Sheet object for the newly created sheet, limited to the following attributes:

  • id
  • name
  • accessLevel
  • permalink

Example request:

curl https://api.smartsheet.com/1.1/sheets?include=data,attachments,discussions \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"name":"newsheet", "fromId": 7679398137620356}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "accessLevel": "OWNER",

        "id": 7960873114331012,

        "name": "newsheet",

        "permalink": "https://smartsheet.com/home?lx=lbKEF1UakfTNJTZ5XkpxWg"

    },

    "resultCode": 0

}

Delete Sheet

Deletes the sheet specified in the URL.

Method

DELETE /sheet/{sheetId}

Access Scope

DELETE_SHEETS

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "resultCode": 0,

    "message": "SUCCESS"

}

Update Sheet

Updates (renames) the sheet specified in the URL.

To modify sheet contents, see Insert Rows into Sheet, Modify Row, Update Row Cells, and Modify Column.

Method

PUT /sheet/{sheetId}

Access Scope

ADMIN_SHEETS

Headers

Content-type: application/json

Request Body

JSON-formatted Sheet object, limited to the following attribute:

  • name (string)

Name need not be unique.

Returns

Result object containing a Sheet object for the newly updated sheet.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"name":"New Sheet Name"}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "accessLevel": "OWNER",

        "id": 7960873114331012,

        "name": "New Sheet Name",

    },

    "resultCode": 0

}

Get Sheet Version

Returns 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

Method

GET /sheet/{sheetId}/version

Access Scope

READ_SHEETS

Returns

A simple object with only a "version" attribute.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/version \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "version": "23"

}

Send Sheet

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

Method

POST /sheet/{sheetId}/emails

Access Scope

SHARE_SHEETS

Request Body

A SheetEmail object

Returns

A Result object

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/emails \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"to" : ["john.doe@smartsheet.com", "jane.doe@smartsheet.com"], "subject" : "Check these rows out!", "message": "Here are the rows I mentioned in our meeting","ccMe":false,"format":"PDF","formatDetails":{"paperSize":"A4"}}'

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Search Sheet

Search sheet.

See Search > Search Sheet for more information.

Share Sheet

See Sharing.

Sheet Columns

Get Columns

Returns the columns on the sheet.

Method

GET /sheet/{sheetId}/columns

Access Scope

READ_SHEETS

Parameters

include

(optional)

When specified with a value of "filters", includes this user's column filters defined for this sheet.

Returns

Array of Column objects.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/columns \

-H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

[

    {

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

    }

]

Add Column to Sheet

Inserts a column into the sheet. See Column Types for more information.

Method

POST /sheet/{sheetId}/columns

Access Scope

ADMIN_SHEETS

Headers

Content-Type: application/json

Request Body

JSON-formatted Column object with the following attributes:

  • title
  • type
  • symbol (optional)
  • options (optional) - array of options
  • index (zero-based)
  • systemColumnType (optional)
  • autoNumberFormat (optional)
  • width (optional)

Returns

Result object containing Column object for the newly created column.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/columns \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"title":"Status", "type":"PICKLIST", "options":["Not Started","Started","Completed"], "index":1}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "id": 5005385858869124,

        "index": 1,

        "title": "Status",

        "type": "PICKLIST"

    },

    "resultCode": 0

}

Sheet Rows

RowWrapper Object

An object for specifying a row or set of rows’ expanded state or location within a sheet.

expanded

boolean

true if the row is expanded, false if it’s collapsed

toTop

boolean

puts the row at the top of the sheet

toBottom

boolean

puts the row at the bottom of the sheet

parentId

number

puts the row as the first child of this row.

siblingId

number

puts the row as the next row at the same hierarchical level of this row.

rows

Row[]

an array of Row objects

Insert Rows into Sheet

Inserts rows into the sheet. Note that all rows are added at the same hierarchical level, as specified by the RowWrapper. Currently we do not support different levels of hierarchy within the inserted rows.

See Contact List Columns for information on inserting cells for columns of type CONTACT_LIST.

Method

POST /sheet/{sheetId}/rows

Access Scope

WRITE_SHEETS

Headers

Content-Type: application/json

Request Body

JSON-formatted RowWrapper object with the following required attributes:

One of:

  • toTop
  • Inserts the rows at the top of the sheet.
  • toBottom
  • Inserts the rows at the bottom of the sheet
  • parentId
  • Inserts the rows as the first child row of the parent. toBottom=true can also be set to add the row as the last child of the parent.
  • siblingId
  • Inserts the row as the next sibling of the row ID provided.

A "rows" attribute set to an array of Row objects, containing at least one Row object.  

Each Row object must have the "cells" attribute set to an array of Cell objects.

Cell objects must have the following attributes set:

  • columnId
  •  value
  • strict (optional)
  • format (optional)
  • hyperlink (optional)

See Column Types and Update Row Cells for more information.

Returns

Result object containing an array of newly inserted Row objects. Result object also returns the new version of the sheet.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/rows \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"toTop":true, "rows":[ {"cells": [ {"columnId": 7960873114331012, "value": true}, {"columnId": 642523719853956, "value": "New status", "strict": false} ] }, {"cells": [ {"columnId": 7960873114331012, "value": true}, {"columnId": 642523719853956, "value": "New status", "strict": false} ] } ] }'

Example response:

{

    "message": "SUCCESS",

    "result": [

        {

            "cells": [

                {

                    "columnId": 7960873114331012,

                    "type": "CHECKBOX",

                    "value": true

                },

                {

                    "columnId": 642523719853956,

                    "displayValue": "New status",

                    "type": "TEXT_NUMBER",

                    "value": "New status"

                }

            ],

            "createdAt": "2013-02-28T17:45:13-08:00",

            "expanded": true,

            "id": 7670198317672324,

            "modifiedAt": "2013-02-28T17:45:13-08:00",

            "rowNumber": 1,

            "sheetId": 2331373580117892

        },

        {

            "cells": [

                {

                    "columnId": 7960873114331012,

                    "type": "CHECKBOX",

                    "value": true

                },

                {

                    "columnId": 642523719853956,

                    "displayValue": "New status",

                    "type": "TEXT_NUMBER",

                    "value": "New status"

                }

            ],

            "createdAt": "2013-02-28T17:45:13-08:00",

            "expanded": true,

            "id": 2040698783459204,

            "modifiedAt": "2013-02-28T17:45:13-08:00",

            "rowNumber": 2,

            "sheetId": 2331373580117892

        }

    ],

    "resultCode": 0

}

Get Row by Number

Get row by its number in the Sheet.

Method

GET /sheet/{sheetId}/row/{rowNumber}

Access Scope

READ_SHEETS

Headers

Content-Type: application/json

Returns

Row object.

Note: rowNumber is 1-based meaning it starts at 1.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/row/{rowNumber} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "id": 2361756178769796,

    "sheetId": 4583173393803140,

    "rowNumber": 1,

    "expanded": true,

    "cells": [

        {

            "type": "TEXT_NUMBER",

            "value": "Revision 1",

            "displayValue": "Revision 1",

            "columnId": 4583173393803140

        },

        {

            "type": "PICKLIST",

            "value": "completed",

            "displayValue": "completed",

            "columnId": 2331373580117892

        }

    ],

    "createdAt": "2012-07-24T23:10:55-07:00",

    "modifiedAt": "2012-07-24T23:14:27-07:00"

}

Sheet Attachments

See Attach File and Attach URL for details on creating Attachments.

Get Sheet Attachments

Returns a list of all Attachments that are on the sheet, including sheet, row and discussion level Attachments.

Method

GET /sheet/{sheetId}/attachments

Access Scope

READ_SHEETS

Returns

An array of Attachment objects.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachments \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

  {

    "name": "att3.png",

    "attachmentType": "FILE",

    "mimeType": "image/png",

    "id": 4583173393803140,

    "parent" : "SHEET",

    "parentId" : 341847495283

  },

  {

    "name": "att4.png",

    "attachmentType": "FILE",

    "mimeType": "image/png",

    "id": 4583173393803140,

    "parent" : "ROW",

    "parentId" : 684956754834557

  }

]

Attach File

See Attach File.

Attach URL

See Attach URL.

Sheet Discussions

See Create Discussion for details on creating sheet-level Discussions..

Sheet Publishing

A Sheet Publish object represents the publish status of a sheet.

Sheet Publish Object

readOnlyLiteEnabled

boolean

status of Read-Only HTML

readOnlyFullEnabled

boolean

status of Read-Only Full

readWriteEnabled

boolean

status of Edit by Anyone

icalEnabled

boolean

status of iCal.

readOnlyLiteUrl

string

URL for Read-Only HTML

readOnlyFullUrl

string

URL for Read-Only Full

readWriteUrl

string

URL for Edit by Anyone

icalUrl

string

URL for iCal

Get Publish Status

Returns the status of the Publish settings of the sheet, including the URLs of any enabled publishings.

Method

GET /sheet/{sheetId}/publish

Access Scope

READ_SHEETS

Returns

A Sheet Publish object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/publish \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

"readOnlyLiteEnabled": true,

"readOnlyFullEnabled": false,

"readWriteEnabled": false,

"icalEnabled": false,

"readOnlyLiteUrl": "https://publish.smartsheet.com/6d35fa6c99334d4892f9591cf6065"

}

Set Publish Status

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

Method

PUT /sheet/{sheetId}/publish

Access Scope

ADMIN_SHEETS

Request Body

A SheetStatus object limited to the following attributes

  • readOnlyLiteEnabled
  • readOnlyFullEnabled
  • readWriteEnabled
  • icalEnabled

Returns

Result object containing a SheetPublish object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/publish \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{"readOnlyLiteEnabled": true,"readOnlyFullEnabled": false,"readWriteEnabled": false,"icalEnabled": false}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "icalEnabled": false,

        "readOnlyFullEnabled": false,

        "readOnlyLiteEnabled": true,

        "readOnlyLiteUrl": "http://publish.smartsheet.com/9862638d9c444014b5d7a114d436e99d",

        "readWriteEnabled": false

    },

    "resultCode": 0

}

Reports

Using /home, you can retrieve a list of available Reports.

Report Object

Extends Sheet, adding the following:

sourceSheet

array

array of Sheet objects (without rows)

The sheets that rows in the report originated from.  Only included if the "include=sourceSheets" parameter is specified.

Report Column Object

Extends Column.  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 their actual column from their source sheet via their columnId attribute.

virtualId

number

The virtual ID of this report column

sheetNameColumn

boolean, "true"

Only included for the special "Sheet Name" report column.

Report Row Object

Extends Row, adding the following:

sheetId

number

The ID of the sheet that this row originates from.

Report Cell Object

Extends Cell, adding the following:

virtualColumnId

number

The virtualId of this cell's column.  virtualColumnId refers to this cell's parent column in this report, while columnId refers to the cell's parent column in its originating source sheet.

Methods

Get Report

Returns the report, including one page of rows, and optionally populated with discussions, attachments, and source sheets.

Method

GET /report/{reportId}

Access Scope

READ_SHEETS

Parameters

include

(optional)

Comma-separated list of optional objects to include in the response:

  • discussions
  • attachments
  • format
  • sourceSheets

pageSize

(optional)

Number of rows per page.  This operation will return a minimum of 1 row, and a maximum of 500.  If not specified, the default value is 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

Report object, populated according to the "include" parameter.

Example request:

curl https://api.smartsheet.com/1.1/report/{reportId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "id": 4583173393803140,

    "name": "My Report",

    "totalRowCount": 4,

    "accessLevel": "OWNER",

    "permalink": "https://smartsheet.com/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"

                }

            ]

        }

    ]

}

Send Report

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

Method

POST /report/{reportId}/emails

Access Scope

SHARE_SHEETS

Request Body

A SheetEmail object

Returns

A Result object

Example request:

curl https://api.smartsheet.com/1.1/report/{reportId}/emails \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"to" : ["john.doe@smartsheet.com", "jane.doe@smartsheet.com"], "subject" : "Check these rows out!", "message": "Here are the rows I mentioned in our meeting","ccMe":false,"format":"PDF","formatDetails":{"paperSize":"A4"}}'

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Share Report

See Sharing.

Columns

Columns can be retrieved as part of a sheet.

Column Object

id

number

column ID

index

number

the column index

title

string

the title of the column

primary

boolean

present and true if the column is the primary column.

type

string

one of:

TEXT_NUMBER

DATE

DATETIME

CONTACT_LIST

CHECKBOX

PICKLIST

options

string[]

an array of the options available for the column.

hidden

boolean

indicates whether the column is hidden.

symbol

string

when applicable, one of:

STAR (for CHECKBOX type only)

FLAG (for CHECKBOX type only)

HARVEY_BALLS (for PICKLIST type only)

PRIORITY (for PICKLIST type only)

RYG (for PICKLIST type only)

systemColumnType

string

When applicable, one of:

AUTO_NUMBER

MODIFIED_DATE

MODIFIED_BY

CREATED_DATE

CREATED_BY

autoNumberFormat

AutoNumberFormat

Present when systemColumnType == AUTO_NUMBER

tags

string[]

A set of tags to indicate special columns, one of:

CALENDAR_START_DATE

CALENDAR_END_DATE

GANTT_START_DATE

GANTT_END_DATE

GANTT_PERCENT_COMPLETE

GANTT_DISPLAY_LABEL

GANTT_PREDECESSOR

GANTT_DURATION

GANTT_ASSIGNED_RESOURCE

width

number

display width of the column in pixels

format

string

format descriptor (see Formatting).

filter

Filter

Included only if the "include=filters" query string parameter is specified and this column has a filter applied to it.

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 LIST or CUSTOM.

A LIST filter represents a filter on a list of literal cell values (see "values" attribute).  A CUSTOM filter contains custom filter criteria (see "criteria" attribute).

excludeSelected

boolean

If true, rows containing cells matching the "values" or "criteria" items are excluded instead of included.

values

array

Only included if this 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

array

Only included if this filter is of type CUSTOM.

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

Criteria Object

Represents a criterion defined for a custom column filter.

operator

string

One of the following values representing

  • 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

object

Optional.  Present if a custom filter criteria's operator has one or more arguments.

value2

object

Optional.  Present if a custom filter criteria's operator has two arguments.

Methods

Modify Column

Allows you to move, rename, or change column properties.

Note that you cannot change the type of a Primary column, or any special calendar/Gantt columns. Also, 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.

Method

PUT /sheet/{sheetId}/column/{columnId}

Deprecated as of 11/8/2014:

PUT /column/{columnId}

Access Scope

ADMIN_SHEETS

Request Body

A Column object limited to the following attributes :

  • index (column's new index in the sheet)
  • title
  • sheetId
  • type (optional)
  • options (optional)
  • symbol (optional)
  • systemColumnType (optional)
  • autoNumberFormat (optional)
  • width (optional)
  • format (optional)

Returns

Result object containing Column object that was modified.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/column/{columnId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X PUT \

-d '{"title":"First Column","index":0, "sheetId":SHEET_ID, "type" : "PICKLIST", "options" :["One","Two"]}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "id": 5005385858869124,

        "index": 0,

        "options" : ["One", "Two"],

        "title": "First Column",

        "type": "PICKLIST"

    },

    "resultCode": 0

}

Delete Column

Deletes a column.

Method

DELETE /sheet/{sheetId}/column/{columnId}

Deprecated as of 11/8/2014:

DELETE /column/{columnId}

Access Scope

ADMIN_SHEETS

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/column/{columnId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Rows

Row Object

id

number

row ID

sheetId

number

parent sheet ID

rowNumber

number

row number within the sheet (1-based - starts at 1)

parentRowNumber

number

parent row number (indented items only)

cells

array

array of Cell objects

discussions

array

array of Discussion objects

attachments

array

array of Attachment objects

columns

array

array of Column objects (only available when rows are fetched individually)

expanded

boolean

a flag to indicate if the row is expanded or collapsed

createdAt

timestamp

time row was created

modifiedAt

accessLevel

version

timestamp

String

number

time row was modified

user's permissions on the sheet.

number that is incremented every time a sheet is modified.

format

string

format descriptor (see Formatting)

filteredOut

boolean

Only returned if the "include=filters" query string param is specified.  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.

Methods

Get Row

Gets a row by its Id.

Method

GET /sheet/{sheetId}/row/{rowId}

Deprecated as of 11/8/2014:

GET /row/{rowId}

Access Scope

READ_SHEETS

Parameters

    include

Comma separated list of optional objects to include in the row:

  • discussions
  • attachments
  • columns
  • filters

To include discussion attachments, both attachments and discussions parameters must be present in the query string.

Including the columns will provide 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 this user's column filters with the columns.

Returns

Result object for the ID provided.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/row/{rowId}?include=discussions,attachments,columns \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "id": 2361756178769796,

    "sheetId": 4583173393803140,

    "rowNumber": 1,

    "expanded": true,

    "cells": [

        {

            "type": "TEXT_NUMBER",

            "value": "Revision 1",

            "displayValue": "Revision 1",

            "columnId": 4583173393803140

        },

        {

            "type": "PICKLIST",

            "value": "completed",

            "displayValue": "completed",

            "columnId": 2331373580117892

        }

    ],

    "createdAt": "2012-07-24T23:10:55-07:00",

    "modifiedAt": "2012-07-24T23:14:27-07:00"

}

Modify Row

Allows you to expand/collapse a row or modify its position (including indenting/outdenting). All child rows are moved with the row.

Method

PUT /sheet/{sheetId}/row/{rowId}

Deprecated as of 11/8/2014:

PUT /row/{rowId}

Access Scope

WRITE_SHEETS

Request Body

A Row object containing the following properties:

  • cells (optional); see the section on updating cells for information on allowed properties
  • expanded (optional)
  • format (optional)
  • One of the position properties:
  • toTop: moves  the row (and children rows, if any) to the top of the sheet.
  • toBottom: moves the row to the bottom of the sheet
  • parentId: moves the row as the first child row of the parent. toBottom=true can also be set to add the row as the last child of the parent.
  • siblingId: moves the row as the next sibling of the row ID provided.

Returns

Result object containing an array of Row objects that have been moved by the operation.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/row/{rowId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{"parentId": PARENT_ROW_ID, "expanded": true}'

Example response:

{

    "message": "SUCCESS",

    "result": [

        {

            "cells": [

                {

                    "columnId": 642523719853956,

                    "displayValue": "1",

                    "type": "TEXT_NUMBER",

                    "value": 1.0

                }

            ],

            "createdAt": "2013-02-28T10:48:42-08:00",

            "expanded": true,

            "id": 3377704922834820,

            "modifiedAt": "2013-02-28T17:45:13-08:00",

            "parentRowNumber": 4,

            "rowNumber": 5

        }

    ],

    "resultCode": 0

}

Delete Row

Deletes the row  by its Id. Note that this will delete ALL child rows of the row specified.

Method

DELETE /sheet/{sheetId}/row/{rowId}

Deprecated as of 11/8/2014:

DELETE /row/{rowId}

Access Scope

WRITE_SHEETS

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/row/{rowId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

   "message": "SUCCESS",

   "resultCode": 0

}

Send Row

Sends a row via email.

Method

POST /sheet/{sheetId}/row/{rowId}/emails

Deprecated as of 11/8/2014:

POST /row/{rowId}/emails

Access Scope

SHARE_SHEETS

Request Body

A RowEmail object.

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/row/{rowId}/emails \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"to" : ["john.doe@smartsheet.com", "jane.doe@smartsheet.com"], "subject" : "Check this row out!", "message": "Here are the rows I mentioned in our meeting", "ccMe" : false, "includeAttachments" : false, "includeDiscussions" : true}'

Example response:

{

   "message": "SUCCESS",

   "resultCode": 0

}

Row Cells

Cell Object

The cell that holds data in a sheet.

type

string

See type definition on Column object.

value

string

This can be either a string, a number or a boolean, depending on the cell type and the data in the cell.

displayValue

string

visual representation of cell contents, as presented to the user in the UI

columnId

number

The id of the column this cell is in.

link

Link

the link, if set, that a cell references. See Link definition.

NOTE: this property is deprecated as of the 8/23/2014 release, replaced by hyperlink, linkInFromCell, and linksOutToCells

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.

linksOutToCells

array

array of CellLinks.  Zero or more outbound links from this cell to cells in other sheets whose values mirror this cell's.

formula

string

the formula for a cell, if set.

format

string

format descriptor (see Formats)

Cell History Object

Extends Cell Object

modifiedAt

string

The datetime for when the change was made to this value

modifiedBy

User

The User that made the change.

Creating and Updating Links

As of the 8/23/2014 API release, you can now create and modify hyperlinks and cell links, using any API operation that creates or updates cell data.

Hyperlinks

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.

Cell Links

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.

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

Example request:

curl https://api.smartsheet.com/1.1/row/{rowId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{"cells":[ { "columnId": 642523719853956, "value": null, "hyperlink": { "url": "http://www.google.com" } } ] }'

Example response:

{

    "message": "SUCCESS",

    "result": [

        {

            "cells": [

                {

                    "columnId": 642523719853956,

                    "displayValue": "http://www.google.com",

                    "type": "TEXT_NUMBER",

                    "value": "http://www.google.com",

                    "hyperlink": {

                        "url": "http://www.google.com"

                    }

                }

            ],

            "createdAt": "2013-02-28T10:48:42-08:00",

            "expanded": true,

            "id": 3377704922834820,

            "modifiedAt": "2013-02-28T17:45:13-08:00",

            "parentRowNumber": 4,

            "rowNumber": 5

        }

    ],

    "resultCode": 0

}

Update Row Cells

Deprecated — You should now use PUT /sheet/{sheetId}/row/{rowId} for updating cells.

Updates the values of the Cells in a Row.

See Contact List Columns for information on inserting cells for columns of type CONTACT_LIST.

Method

PUT /row/{rowId}/cells

Access Scope

WRITE_SHEETS

Request Body

An array of Cells to be updated.  

Cells are limited to the following required attributes:

  • columnId
  • value
  • 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:
  • sheetId
  • rowId
  • columnId

See Column Types for more information. Note that the columnIds must be valid for the sheet to which the Row belongs, and must only be used once per operation. Note that cells containing formulas cannot be updated. Also, 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 an array of updated Cell objects. Result object also returns the new version of the sheet.

Example request:

curl https://api.smartsheet.com/1.1/row/{rowId}/cells \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '[ {"columnId": 3738748463671172, "value": "Revision 2"}, {"columnId": 5427598323935108, "value": "On Time", "strict": false} ]'

Example response:

{

    "message": "SUCCESS",

    "result": [

        {

            "columnId": 642523719853956,

            "displayValue": "Revision 2",

            "type": "TEXT_NUMBER",

            "value": "Revision 2"

        },

        {

            "columnId": 5146123347224452,

            "displayValue": "On Time",

            "type": "PICKLIST",

            "value": "On Time"

        }

    ],

    "resultCode": 0

}

Get Cell History

Gets the cell modification history. Note that this is a resource-intensive operation and incurs 10 additional requests against the rate limit.

Method

GET /sheet/{sheetId}/row/{rowId}/column/{columnId}/history

Deprecated as of 11/8/2014:

GET /row/{rowId}/column/{columnId}/history

Access Scope

READ_SHEETS

Returns

An array of Cell History Objects

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/row/{rowId}/column/{columnId}/history \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

        {

          "columnId":642523719853956,

          "displayValue": "Revision 3",

           "type": "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",

           "type": "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",

           "type": "TEXT_NUMBER",

           "value": "Revision 1",

           "modifiedAt": "2013-06-22T00:10:18Z",

           "modifiedBy" : {

              "name" : "Joe Smart",

              "email" : "joe.smart@smartsheet.com"

           

             }

        }

]

Row Attachments

See Attach File and Attach URL for details on creating Row-level attachments

Get Row Attachments

Returns a list of all Attachments that are on the row, including row and discussion level Attachments.

Method

GET /sheet/{sheetId}/row/{rowId}/attachments

Deprecated as of 11/8/2014:

GET /row/{rowId}/attachments

Access Scope

READ_SHEETS

Returns

A List of Attachment objects.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/row/{rowId}/attachments \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

  {

    "name": "att3.png",

    "attachmentType": "FILE",

    "mimeType": "image/png",

    "id": 4583173393803140,

    "parent" : "ROW",

    "parentId" : 341847495283

  },

  {

    "name": "att4.png",

    "attachmentType": "FILE",

    "mimeType": "image/png",

    "id": 4583173393803140,

    "parent" : "COMMENT",

    "parentId" : 684956754834557

  }

]

Attach File

See Attach File.

Attach URL

See Attach URL.

Row Discussions

See Create Discussion for details on creating a new Discussion on a Row.

Attachments

Attachment Object

id

number

attachment ID

name

string

attachment name

url

string

attachment temporary URL (files only)

urlExpiresInMillis

number

attachment temporary URL time to live (files only)

attachmentType

string

attachment type (one of FILE, GOOGLE_DRIVE, LINK, BOX_COM, DROPBOX, or EVERNOTE)

attachmentSubType

string

attachment sub type, only for GOOGLE_DRIVE type attachments; one of (DOCUMENT, SPREADSHEET,  PRESENTATION, PDF, DRAWING)

createdAt

timestamp

a timestamp of when the attachment was originally added.

createdBy

User

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

Methods

Get Attachment

Fetches an attachment based on the Attachment id.

Method

GET /sheet/{sheetId}/attachment/{attachmentId}

Deprecated as of 11/8/2014:

GET /attachment/{attachmentId}

Access Scope

READ_SHEETS

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.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachment/{attachmentId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "name": "at3.png",

    "url": "URL_TO_ATTACHMENT",

    "attachmentType": "file",

    "mimeType": "image/png",

    "id": 4583173393803140,

    "urlExpiresInMillis": 120000

}

Posting an Attachment

Smartsheet UI allows attaching files to Sheets, Rows and Comments. The same is true for the API. To upload a file, send a POST request to one of the following URLs, depending on your use case:

https://api.smartsheet.com/1.1/sheet/{sheetId}/attachments

https://api.smartsheet.com/1.1/sheet/{sheetId}/row/{rowId}/attachments

https://api.smartsheet.com/1.1/sheet/{sheetId}/comment/{commentId}/attachments

When posting an attachment, you must set specific headers to tell Smartsheet about the file. All three of the following headers are required. Here is an example :

Content-Disposition: attachment; filename="ProgressReport.docx"

Content-Type: application/msword

Content-Length: 5463

Content-Disposition tells us that a file is in the body of the POST request and what the name of the file is. Content-Type can be left blank (but must be present) if it is not known, and Smartsheet 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, in UNIX:

        $ ls -l ProgressReport.docx

        5463 ProgressReport.docx

NOTE: Multipart or chunked file uploads are not supported at this time.

NOTE: For attachment file size limits, please see our Help Center article on Uploading Attachments.

NOTE: This is a resource-intensive operation and incurs 10 additional requests against the rate limit.

All that is left is to include the file in the body of the post. 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. Using curl, it looks like this:

 curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachments \

 -H 'Authorization: Bearer ACCESS_TOKEN'  \

 -H 'Content-Disposition: attachment; filename="ProgressReport.docx"'  \

 -H 'Content-Type: application/msword'  \

 -H 'Content-Length: 5463'  \

 -X POST \

 --data-binary @ProgressReport.docx

Attach File

Attaches a file to the Sheet, Row or Comment. Note that this is a resource-intensive operation and incurs 10 additional requests against the rate limit.

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

Method

POST /sheet/{sheetId}/attachments

POST /sheet/{sheetId}/row/{rowId}/attachments

POST /sheet/{sheetId}/comment/{commentId}/attachments

Deprecated as of 11/8/2014:

POST /row/{rowId}/attachments

POST /comment/{commentId}/attachments

Access Scope

WRITE_SHEETS

Request Body

The actual file to attach.

Headers

Content-Disposition

Content-Type

Content-Length

See Posting an Attachment for details.

Returns

Result object containing Attachment object for newly created attachment.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachments \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/msword" \

-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \

-H "Content-Length: FILE_SIZE" \

-X POST \

--data-binary @ProgressReport.docx

Example reponse:

{

    "message": "SUCCESS",

    "result": {

        "attachmentType": "FILE",

        "createdAt": "2013-02-28T21:04:56-08:00",

        "id": 4583173393803140,

        "mimeType": "application/msword",

        "name": "ProgressReport.docx"

    },

    "resultCode": 0

}

Attach URL

Attaches a URL to a sheet, row or comment. This url can be a normal URL (attachmentType "LINK"), a Google Drive URL (attachmentType "GOOGLE_DRIVE") a Box.com URL (attachmentType "BOX_COM"), a Dropbox URL (attachmentType “DROPBOX”), or an Evernote URL (attachmentType “EVERNOTE”).

NOTE: attachmentSubType is valid only for GOOGLE_DRIVE attachments which are Google Docs.  It can optionally be included to indicate the type of a file.  The following attachmentSubTypes are valid for GOOGLE_DRIVE attachments "DOCUMENT", "SPREADSHEET", "PRESENTATION", "PDF", "DRAWING".

NOTE: when the attachment type is BOX_COM, DROPBOX, or GOOGLE_DRIVE (without an attachmentSubType specified), the mimeType will be derived by the file extension specified on the "name".

Method

POST /sheet/{sheetId}/attachments

POST /sheet/{sheetId}/row/{rowId}/attachments

POST /sheet/{sheetId}/comment/{commentId}/attachments

Deprecated as of 11/8/2014:

POST /row/{rowId}/attachments

POST /comment/{commentId}/attachments

Access Scope

WRITE_SHEETS

Request Body

An Attachment object limited to the following attributes:

  • name
  • description (applicable when attaching to sheet or row only)
  • url
  • attachmentType
  • attachmentSubType

Returns

Result object containing Attachment object for newly created attachment.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachments \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'

Example reponse:

{

    "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

}

Delete Attachment

Deletes attachment.  If the attachment has multiple versions this deletes only the specific version specified by the attachmentId (each version has a different attachment ID).

Method

DELETE /sheet/{sheetId}/attachment/{attachmentId}

Deprecated as of 11/8/2014:

DELETE /attachment/{attachmentId}

Access Scope

WRITE_SHEETS

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachment/{attachmentId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Attachment Versions

Methods

Get All Versions

Gets a list of all versions of the given attachment ID, in order from newest to oldest.  Note: for file attachments, to retrieve a download URL, use the Get Attachment operation for the specific version you want to download.

Method

GET /sheet/{sheetId}/attachment/{attachmentId}/versions

Deprecated as of 11/8/2014:

GET /attachment/{attachmentId}/versions

Access Scope

READ_SHEETS

Returns

Attachment object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachment/{attachmentId}/versions \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

{

    "id": 4583173393803140,

    "name": "at3.png",

    "attachmentType": "file",

    "mimeType": "image/png",

    "createdAt": "2014-03-28T18:13:20-07:00",

},

{

    "id": 4583173393803140,

    "name": "at3.png",

    "attachmentType": "file",

    "mimeType": "image/png",

    "createdAt": "2014-03-27T18:11:11-07:00",

},

]

Upload New Version

Once a file has been attached to a Sheet or Row, you can use this operation to upload new versions of it.

Note: Uploading new versions is not supported for attachments on Comments or for URL attachments.

Method

POST /sheet/{sheetId}/attachment/{attachmentId}/versions

Deprecated as of 11/8/2014:

POST /attachment/{attachmentId}/versions

Access Scope

WRITE_SHEETS

Request Body

The actual file to attach.

Headers

Content-Disposition

Content-Type

Content-Length

See Posting an Attachment for details.

Returns

Result object containing Attachment object for newly created attachment.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachment/{attachmentId}/versions \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/msword" \

-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \

-H "Content-Length: FILE_SIZE" \

-X POST \

--data-binary @ProgressReport.docx

Example reponse:

{

    "message": "SUCCESS",

    "result": {

        "attachmentType": "FILE",

        "createdAt": "2013-02-28T21:04:56-08:00",

        "id": 4583173393803140,

        "mimeType": "application/msword",

        "name": "ProgressReport.docx"

    },

    "resultCode": 0

}

Delete All Versions

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

Method

DELETE /sheet/{sheetId}/attachment/{attachmentId}/versions

Deprecated as of 11/8/2014:

DELETE /attachment/{attachmentId}/versions

Access Scope

WRITE_SHEETS

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/attachment/{attachmentId}/versions \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Discussions

Discussion Object

id

number

discussion ID

title

string

discussion title

comments

array

array of Comment objects

commentAttachments

array

array of Attachment objects

lastCommentedAt

timestamp

time of most recent comment

lastCommentedUser

User

author of most recent comment

createdBy

User

creator of this discussion

Methods

Get Discussion

Gets a Discussion by its ID.

Method

GET /sheet/{sheetId}/discussion/{discussionId}

Deprecated as of 11/8/2014:

GET /discussion/{discussionId}

Access Scope

READ_SHEETS

Returns

Discussion object for the ID provided.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/discussion/{discussionId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "title": "This is a new discussion",

    "id": 2331373580117892,

    "comments": [

        {

            "id": 2331373580117892,

            "text": "This text is the body of the discussion",

            "createdBy": {

                "email": "john.doe@smartsheet.com"

            },

            "modifiedDate": "2012-07-25T00:02:42-07:00"

        }

    ]

}

Create Discussion

Creates a new Discussion on a Sheet or Row.

Method

POST /sheet/{sheetId}/discussions

POST /sheet/{sheetId}/row/{rowId}/discussions

Deprecated as of 11/8/2014:

POST /row/{rowId}/discussions

Access Scope

WRITE_SHEETS

Headers

Content-Type: application/json

Request Body

Discussion object with the following attributes:

  • title (string)
  • comment (Comment object)

Returns

Result object containing Discussion object for the newly created discussion.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/discussions \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"title": "This is a new discussion", "comment": {"text":"This text is the body of the first comment"}}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "comments": [

            {

                "createdAt": "2013-02-28T22:00:56-08:00",

                "createdBy": {

                    "email": "jane.doev@smartsheet.com",

                    "name": Jane Doe"

                },

                "id": 4583173393803140,

                "modifiedAt": "2013-02-28T22:00:56-08:00",

                "modifiedDate": "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

}

Delete Discussion

Deletes a discussion by id.

Method

DELETE /sheet/{sheetId}/discussion/{discussionId}

Deprecated as of 11/8/2014:

DELETE /discussion/{discussionId}

Access Scope

WRITE_SHEETS

Headers

Content-Type: application/json

Returns

A Result object indicate success of the operation.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/discussion/{discussionId} \

-H "Authorization: Bearer ACCESS_TOKEN"\

-X 'DELETE'

Example response:

{

   "resultCode": 0,

   "message" : "SUCCESS"

}

Add Comment

Adds a Comment to a Discussion.

Method

POST /sheet/{sheetId}/discussion/{discussionId}/comments

Deprecated as of 11/8/2014:

POST /discussion/{discussionId}/comments

Access Scope

WRITE_SHEETS

Headers

Content-Type: application/json

Request Body

Comment object with the following attribute:

  • text

Returns

Result object containing Comment object that was created.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/discussion/{discussionId}/comments \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"text":"This is a new comment."}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "createdAt": "2013-02-28T22:58:30-08:00",

        "createdBy": {

            "email": "john.doe@smartsheet.com",

            "name": "John Doe"

        },

        "id": 6834973207488388,

        "modifiedAt": "2013-02-28T22:58:30-08:00",

        "modifiedDate": "2013-02-28T22:58:30-08:00",

        "text": "This is a new comment."

    },

    "resultCode": 0

}

Get Discussion Attachments

Returns a list of all Attachments that are in the discussion.

Method

GET /sheet/{sheetId}/discussion/{discussionId}/attachments

Deprecated as of 11/8/2014:

GET /discussion/{discussionId}/attachments

Access Scope

READ_SHEETS

Returns

A List of Attachment objects.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/discussion/{discussionId}/attachments \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

  {

    "name": "att3.png",

    "attachmentType": "FILE",

    "mimeType": "image/png",

    "id": 4583173393803140,

    "parent" : "COMMENT",

    "parentId" : 341847495283

  },

  {

    "name": "att4.png",

    "attachmentType": "FILE",

    "mimeType": "image/png",

    "id": 4583173393803140,

    "parent" : "COMMENT",

    "parentId" : 684956754834557

  }

]

Comments

Comment Object

id

number

comment ID

text

string

comment body

createdBy

User

comment's author

modifiedDate

timestamp

time of last modification

attachments

discussionId

array

number (optional)

array of Attachment objects

discussion ID

Methods

Get Comment

Gets a comment by id.

Method

GET /sheet/{sheetId}/comment/{commentId}

Deprecated as of 11/8/2014:

GET /comment/{commentId}

Access Scope

READ_SHEETS

Headers

Content-Type: application/json

Returns

A Comment object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/comment/{id} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "text": "This is a comment",

    "createdBy" : {"name": "John Doe", "email" : "john.doe@smartsheet.com"}

    "createdAt" : "2013-06-24T21:07:45Z"

    "id": 48569348493401200

}

Delete Comment

Deletes a comment by id.

Method

DELETE /sheet/{sheetId}/comment/{commentId}

Deprecated as of 11/8/2014:

DELETE /comment/{commentId}

Access Scope

WRITE_SHEETS

Headers

Content-Type: application/json

Returns

A Result object indicate success of the operation.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/comment/{commentId} \

-H "Authorization: Bearer ACCESS_TOKEN"\

-X 'DELETE'

Example response:

{

   "resultCode": 0,

   "message" : "SUCCESS"

}

Attach File

See Attach File.

Attach URL

See Attach URL.

Users

User Object

id

integer

user's ID

email

string

user's email

name

string (optional)

user's full name. This is a read-only field.

firstName

string (optional)

user's first name.

lastName

string (optional)

user's last name

admin

boolean

system admin? (can manage users and account)

licensedSheetCreator

boolean

licensed user? (can create and own sheets)

groupAdmin

boolean

group admin? (can create and edit groups)

resourceManager

boolean

resource viewer? (can access resource views)

status

string

one of ACTIVE, PENDING or DECLINED

User Profile Object

id

integer

the current user's ID

email

string

the current user's email

firstName

string

the current user's first name

lastName

string

the current user's last name

timeZone

string

the current user’s time zone ID

locale

string

the current user’s locale (see Server Information for locale list)

Methods

These methods are available to account administrators only.  See Admin Features for more information.

List All Users

Lists all users in the organization.  You can optionally specify a list of email addresses of users to narrow down the results using the "email" query string parameter.

Method

GET /users

Access Scope

ADMIN_USERS

Parameters

    email

    (optional)

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

Returns

Array of  User objects.

Example request:

curl https://api.smartsheet.com/1.1/users?email=john.doe@smartsheet.com \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "id": 94094820842,

        "admin": true,

        "email": "john.doe@smartsheet.com",

        "name": "John Doe",

        "licensedSheetCreator": true,

        "status": "ACTIVE"

    }

]

Add User

Adds a user to the organization. If successful, will trigger the same invitation flow as it would in the web application.

Method

POST /users

Access Scope

ADMIN_USERS

Headers

Content-Type: application/json

Parameters

    sendEmail

    (optional)

A boolean flag to indicate whether to send a welcome email or not. Defaults to false.

Request Body

User object with the following attributes:

  • email (required)
  • admin (required)
  • licensedSheetCreator (required)
  • firstName (optional)
  • lastName (optional)
  • resourceManager (optional)

Returns

Result object. If operation successful, will include User object for the created user.

Note: the resourceManager attribute is equivalent to the resourceViewer role in the product.

Example request:

curl https://api.smartsheet.com/1.1/users?sendEmail=true \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"firstName": "John", "lastName": "Doe", "email": "NEW_USER_EMAIL", "admin": false, "licensedSheetCreator": true}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "admin": false,

        "email": "NEW_USER_EMAIL",

        "name": "John Doe",

        "id": 1768423626696580,

        "licensedSheetCreator": true

    },

    "resultCode": 0

}

Get Current User

Gets the current user.

Method

GET /user/me

Access Scope

all scopes

Headers

Content-Type: application/json

Returns

A User Profile object for the current user.

Example request:

curl https://api.smartsheet.com/1.1/user/me \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "email": "john.doe@smartsheet.com",

    "firstName": "John",

    "lastName": "Doe",

    "id": 48569348493401200

}

Get User

Gets a user by id.

Method

GET /user/{userId}

Access Scope

ADMIN_USERS

Headers

Content-Type: application/json

Returns

A User Profile object for the user specified

Example request:

curl https://api.smartsheet.com/1.1/user/{userId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "email": "john.doe@smartsheet.com",

    "firstName": "John",

    "lastName": "Doe",

    "id": 48569348493401200

}

Update User

Updates a user in the organization.

Method

PUT /user/{userId}

Access Scope

ADMIN_USERS

Headers

Content-Type: application/json

Request Body

User object containing at least one of the following attributes:

  • admin (required)
  • licensedSheetCreator (required)
  • firstName (optional)
  • lastName (optional)
  • resourceManager (optional)

Note: firstName and lastName cannot be updated at this time.

Returns

Result object. If operation successful, will include User object for the created user.

Example request:

curl https://api.smartsheet.com/1.1/user/{userId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{"admin": false, "licensedSheetCreator": true}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "admin": true,

        "licensedSheetCreator": true

    },

    "resultCode": 0

}

Delete User

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

Method

DELETE /user/{userId}

Access Scope

ADMIN_USERS

Parameters

    transferTo

    (optional)

The ID of the user to whom the sheets should be transferred.  Defaults to not transferring the sheets.

    removeFromSharing

    (optional)

Set to "true" to remove the user from sharing all sheets/workspaces in the organization. Defaults to false.

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/user/{userId}?transferTo=USER_ID&removeFromSharing=true \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

List All Sheets

Returns the list of all sheets owned by the members of the account (organization).

Method

GET /users/sheets

Access Scope

ADMIN_USERS

Returns

Array of Sheet objects, limited to the following attributes:

  • id
  • name
  • owner  (email address)
  • ownerId

Example request:

curl https://api.smartsheet.com/1.1/users/sheets \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "id": 2894323533539204,

        "name": "New Sheet",

        "owner": "john.doe@smartsheet.com",

        "ownerId: 995857572373

    }

]

Groups

Group Object

id

integer

group ID

name

string

group name

description

string

group description

owner

string

group owner’s email address

ownerId

integer

group owner’s user ID

members

array

array of Group Member objects

createdAt

timestamp

time group was created

modifiedAt

timestamp

time group was last modified

Group Member Object

id

integer

the group member's user ID

email

string

the group member's email

firstName

string

the group member's first name

lastName

string

the group member's last name

name

string

the group member's full name

Methods

List All Groups

Returns the list of groups in an organization.  To fetch group members, use the GET /group/{id} method.

Method

GET /groups

Access Scope

ADMIN_USERS

Returns

Array of Group objects.

Example request:

curl https://api.smartsheet.com/1.1/groups \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "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 Group

Returns group information, including its members.

Method

GET /group/{groupId}

Access Scope

ADMIN_USERS

Returns

Group object, including a list of Group Member objects.

Example request:

curl https://api.smartsheet.com/1.1/group/{groupId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "id": 4583173393803140,

    "name": "Group 1",

    "description": "My group",

    "owner": "john.doe@smartsheet.com",

    "ownerId": 2331373580117892,

    "members": [

        {

            "id": 2331373580117892,

            "email": "john.doe@smartsheet.com",

            "firstName": "John",

            "lastName": "Doe",

            "name": "John Doe"

        },

    ],

    "createdAt": "2014-05-29T14:41:35-07:00",

    "modifiedAt": "2014-05-29T14:41:35-07:00"

}

Create Group

Creates a new group.  NOTE: this method is only available to group administrators.

Method

POST /groups

Access Scope

ADMIN_USERS

Headers

Content-Type: application/json

Request Body

JSON-formatted Group object, limited to the following attributes:

  • name; must be unique within the organization
  • description (optional)
  • members (optional array of Group Member objects limited to the following attributes)
  • email

Returns

Result object, containing a Group object for the newly-created group.

Example request:

curl https://api.smartsheet.com/1.1/group/{groupId} \

-H "Authorization: Bearer ACCESS_TOKEN"

-H "Content-Type: application/json" \

-X POST \

-d '{ "name": "API-created Group", "description": "Group created via API", "members": [{ "email": "john.doe@smartsheet.com" }]}'

Example response:

{

    "resultCode": 0,

    "result": {

        "id": 2331373580117892,

        "name": "API-created Group",

        "description": "Group created via API",

        "owner": "john.doe@smartsheet.com",

        "ownerId": 4583173393803140,

        "members": [

            {

                "id": 4583173393803140,

                "email": "john.doe@smartsheet.com",

                "firstName": "John",

                "lastName": "Doe",

                "name": "John Doe"

            }

        ],

        "createdAt": "2014-05-29T16:28:49-07:00",

        "modifiedAt": "2014-05-29T16:28:49-07:00"

    },

    "message": "SUCCESS"

}

Update Group

Updates a group.  NOTE: this method is only available to group administrators and system administrators.

Method

PUT /group/{groupId}

Access Scope

ADMIN_USERS

Headers

Content-type: application/json

Request Body

JSON-formatted Sheet object, limited to the following attributes:

  • name; must be unique within the organization (optional)
  • description (optional)

Returns

Result object containing Group object for the updated group.

Example request:

curl https://api.smartsheet.com/1.1/group/{groupId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{ "name": "Renamed Group", "description": "Some new description" }'

Example response:

{

    "resultCode": 0,

    "result": {

        "id": 2331373580117892,

        "name": "Renamed Group",

        "description": "Some new description",

        "owner": "john.doe@smartsheet.com",

        "ownerId": 4583173393803140,

        "createdAt": "2014-05-29T16:28:49-07:00",

        "modifiedAt": "2014-05-29T17:00:23-07:00"

    },

    "message": "SUCCESS"

}

Delete Group

Deletes a group.

NOTES:

  • This method is only available to group administrators and system administrators.
  • This operation is asynchronous, meaning group members may retain their sharing access for a brief period of time after the call returns.  For small groups with limited sharing, the operation should complete quickly (within a few seconds).  For large groups with many shares, this operation could possibly take more than a minute to complete.

Method

DELETE /group/{groupId}

Access Scope

ADMIN_USERS

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/group/{groupId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Group Members

Methods for updating members of an existing group.

Add Members to Group

Adds members to a group.

NOTES:

  • This method is only available to group administrators and system administrators.
  • This operation is asynchronous, meaning the users may not yet have sharing access to sheets for a period of time after this operation returns.  For small groups with limited sharing, the operation should complete quickly (within a few seconds).  For large groups with many shares, this operation could possibly take more than a minute to complete.

Method

POST /group/{groupId}/members

Access Scope

ADMIN_USERS

Headers

Content-Type: application/json

Request Body

Array of JSON-formatted Group Member objects, limited to the following attribute:

  • email

Returns

Result object, containing an array of the group members that will be added to the group (duplicate members will be filtered out)

Example request:

curl https://api.smartsheet.com/1.1/group/{groupId}/members \

-H "Authorization: Bearer ACCESS_TOKEN"

-H "Content-Type: application/json" \

-X POST \

-d '[{ "email": "jane.doe@smartsheet.com" }]'

Example response:

{

    "resultCode": 0,

    "result": [

        {

            "id": 1539725208119172,

            "email": "jane.doe@smartsheet.com",

            "firstName": "Jane",

            "lastName": "Doe",

            "name": "Jane Doe"

        }

    ],

    "message": "SUCCESS"

}

Remove Memeber From Group

Removes member from a group.

NOTES:

  • This method is only available to group administrators and system administrators.
  • This operation is asynchronous, meaning group members may retain their sharing access for a brief period of time after the call returns.  For small groups with limited sharing, the operation should complete quickly (within a few seconds).  For large groups with many shares, this operation could possibly take more than a minute to complete.

Method

DELETE /group/{groupId}/member/{userId}

Access Scope

ADMIN_USERS

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/group/{groupId}/member/{userId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Search

Search Result Object

totalCount

number

total number or results

results

array of SearchResultItems

SearchResultItem Object

text

string

search result text excerpt

objectId

number

search result object ID

objectType

string

search result object type (row, discussion, attach.)

parentObjectId

number

search result parent object ID

parentObjectType

string

search result parent object type (row, discussion, attach.)

parentObjectName

string

search result parent object name

contextData

array of strings

additional info on search result context (row num...)

Methods

Search Everything

Performs a search across all Sheets to which user has access.

NOTE: Searching on partial words is supported using wildcards.

NOTE: The number of results returned is limited to one hundred. However

Method

GET /search

Access Scope

READ_SHEETS

Parameters

    query

Text with which to perform the search.

Returns

A SearchResult object. Will contain a maximum of 100

SearchResultems.

Example request:

curl https://api.smartsheet.com/1.1/search?query=stuff \

-H "Authorization: Bearer ACCESS_TOKEN"

Example result:

{

    "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

}

Search Sheet

Method

GET /search/sheet/{sheetId}

Access Scope

READ_SHEETS

Parameters

    query

Text with which to perform the search.

Returns

A SearchResult object. Will contain a maximum of 100

SearchResultems.

Example request:

curl https://api.smartsheet.com/1.1/search/sheet/{sheetId}?query=stuff \

-H "Authorization: Bearer ACCESS_TOKEN"

Example result:

{

    "results": [

        {

            "contextData": [

                "Discussion 1"

            ],

            "objectId": 1888207043356548,

            "objectType": "discussion",

            "parentObjectId": 7141187195824004,

            "parentObjectName": "Sheet 1",

            "parentObjectType": "sheet",

            "text": "discussion stuff goes here"

        }

    ],

    "totalCount": 1

}

Sharing

NOTE: As of the June 7 Smartsheet release, Groups functionality was introduced into the application.  The API has been updated to accommodate this new feature, but in order to preserve backward compatibility with existing API clients, we needed to create new sharing endpoints that support sharing with groups.  See the Sharing with Groups section below.

Going forward, these existing sharing endpoints are considered deprecated, and we recommend using the new endpoints instead.

These sharing endpoints will continue to function as they did previously.  In the case of an object shared to a group, these endpoints will treat a group share as multiple individual shares.  In other words, they do not distinguish between shares to individual users and shares to groups.  For example, if a sheet is shared with a group of five people, GET /sheet/{sheetId}/shares will return five individual user shares, rather than one group share.  Note that you cannot update (PUT) or delete (DELETE) one of these expanded shares; if you try to do so, you will receive an HTTP 404 error with the error code 1027 and message "Share not found".  Use the new endpoints to work with group shares.

Share Object

id

number

user ID

name

string

user name, if user is also a contact

accessLevel

string

user's permissions on shared object

email

string

user's email address

MultiShare Object

users

array

An array of User objects, limited to only an "emailAddress" field

accessLevel

string

user's permissions on workspace

subject

string

The subject of the email that will be sent to notify of the users

message

string

The message to be included in the body of the email that will be sent to the user.

ccMe

boolean

a flag to indicate whether or not to cc the user sharing the sheet.

Methods

Get Shares

Lists all the Users to whom a Sheet or Workspace is shared, and their access level.

Method

GET /sheet/{sheetId}/shares

GET /workspace/{workspaceId}/shares

Access Scope

READ_SHEETS

Returns

Array of Share objects representing those to whom the sheet or workspace has been shared.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/shares \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "accessLevel": "OWNER",

        "email": "jane.doe@smartsheet.com",

        "id": 4583173393803140

    },

    {

        "accessLevel": "OWNER",

        "email": "john.doe@smartsheet.com",

        "id": 7683173393803140

    }

]

Get Share

Returns the access level for the specified user on the specified sheet or workspace .

Method

GET /sheet/{sheetId}/share/{userId}

GET /workspace/{workspaceId}/share/{userId}

Access Scope

READ_SHEETS

Returns

The Share object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/share/{userId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "accessLevel": "OWNER",

    "email": "jane.doe@smartsheet.com",

    "id": 4583173393803140

}

Share to One

Shares a Sheet or Workspace to the user specified.

Method

POST /sheet/{sheetId}/shares

POST /workspace/{workspaceId}/shares

Access Scope

SHARE_SHEETS(when working with Sheets)

ADMIN_WORKSPACES (when working with Workspaces)

Headers

Content-Type: application/json

Request Body

Share object limited to the following attributes:

  • email (string)
  • accessLevel (string)

Parameters

    sendEmail

    (optional)

Either "true" or "false" to  indicate whether or not to notify the user by email. Default is false.

Returns

Result object containing a Share object representing the person to whom the sheet or workspace has just been shared.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/shares?sendEmail=true \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"email":"jane.doe@smartsheet.com", "accessLevel": "EDITOR"}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "accessLevel": "EDITOR",

        "email": "jane.doe@smartsheet.com",

        "id": 1205473673275268

    },

    "resultCode": 0

}

Share to Many

Shares a Sheet or Workspace to the users specified.

Method

POST /sheet/{sheetId}/multishare

POST /workspace/{workspaceId}/multishare

Access Scope

SHARE_SHEETS(when working with Sheets)

ADMIN_WORKSPACES (when working with Workspaces)

Headers

Content-Type: application/json

Request Body

A MultiShare object

Parameters

    sendEmail

    (optional)

Either "true" or "false" to  indicate whether or not to notify the user by email. Default is false.

Returns

Result object containing array of Share objects that were created.  Users to  whom the Sheet or Workspace that had previously been shared remain unchanged and are not included in the return value.

Note: you can share only up to 50 users at a time.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/multishare?sendEmail=true \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"users":[{"email":"john.doe@smartsheet.com"},{"email":"jane.doe@smartsheet.com"}],"subject":"My new Smartsheet","message":"I have shared a Smartsheet with you. Please review it for the latest updates", "accessLevel":"ADMIN","ccMe":false}'

Example response:

{

    "message": "SUCCESS",

    "result": [

        {

            "accessLevel": "ADMIN",

            "email": "john.doe@smartsheet.com",

            "id": 5709073300645764

        },

        {

            "accessLevel": "ADMIN",

            "email": "jane.doe@smartsheet.com",

            "id": 3457273486960516

        }

    ],

    "resultCode": 0

}

Update Share

Updates the access level of a user of the specified Sheet or Workspace.

Method

PUT /sheet/{sheetId}/share/{userId}

PUT /workspace/{workspaceId}/share/{userId}

Access Scope

SHARE_SHEETS(when working with Sheets)

ADMIN_WORKSPACES (when working with Workspaces)

Headers

Content-Type: application/json

Request Body

Share object limited to the following attributes:

  • accessLevel (string)

Returns

Result object containing the modified Share object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/share/{userId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{"accessLevel": "VIEWER"}'

Example response:

{

    "message": "SUCCESS",

    "result": {

        "accessLevel": "VIEWER",

        "email": "jane.doe@smartsheet.com",

        "id": 6834973207488388

    },

    "resultCode": 0

}

Delete Share

Deletes the Share.

Method

DELETE /sheet/{sheetId}/share/{userId}

DELETE /workspace/{workspaceId}/share/{userId}

Access Scope

SHARE_SHEETS(when working with Sheets)

ADMIN_WORKSPACES (when working with Workspaces)

Returns

Result object

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/share/{userId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Sharing with Groups

As of the June 7 Smartsheet release, these are the new endpoints that should be used for working with sharing.  See the old Sharing section for more details on this change.

ShareWithGroups Object

id

string

share ID

NOTE: unlike other Smartsheet object ids, this id is an alphanumeric string

type

string

the type of this share. "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

name

string

user name, if user is also a contact

accessLevel

string

user or group's permissions on shared object

email

string

user's email address; null for group shares

MultiShareWithGroups Object

shares

array

An array of ShareWithGroups objects, limited to one of "userId", "groupId", or "email" fields.

accessLevel

string

share permissions on shared object

subject

string

The subject of the email that will be sent to notify the users

message

string

The message to be included in the body of the email that will be sent to the users.

ccMe

boolean

a flag to indicate whether or not to cc the user sharing the object.

Methods

Get Shares (with Groups)

Lists all the users and groups to whom a Sheet or Workspace is shared, and their access level.

Method

GET /sheet/{sheetId}/shareswithgroups

GET /workspace/{workspaceId}/shareswithgroups

GET /report/{reportId}/shareswithgroups

Access Scope

READ_SHEETS

Returns

Array of ShareWithGroups objects representing those to whom the sheet or workspace has been shared.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/shareswithgroups \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

[

    {

        "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 Share (with Groups)

Returns the access level for the specified user or group on the specified sheet or workspace .

Method

GET /sheet/{sheetId}/sharewithgroup/{shareId}

GET /workspace/{workspaceId}/sharewithgroup/{shareId}

GET /report/{reportId}/sharewithgroup/{shareId}

Access Scope

READ_SHEETS

Returns

The ShareWithGroup object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/sharewithgroup/{shareId} \

-H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{

    "id": "AQAISF82FOeE",

    "type": "GROUP",

    "groupId": 2331373580117892,

    "name": "Group 1",

    "accessLevel": "ADMIN"

}

Share (with Groups) to One

Shares a Sheet or Workspace to the user specified.

Method

POST /sheet/{sheetId}/shareswithgroups

POST /workspace/{workspaceId}/shareswithgroups

POST /report/{reportId}/shareswithgroups

Access Scope

SHARE_SHEETS (when working with Sheets)

ADMIN_WORKSPACES (when working with Workspaces)

Headers

Content-Type: application/json

Request Body

Share object limited to the following attributes:

  • type (string)
  • when type is "USER": userId or email
  • when type is "GROUP": groupId
  • accessLevel (string)

Parameters

    sendEmail

    (optional)

Either "true" or "false" to  indicate whether or not to notify the user by email. Default is false.

Returns

Result object containing a ShareWithGroups object representing the person or group to whom the sheet or workspace has just been shared.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/shareswithgroups?sendEmail=true \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"type": "USER", "userId": 1539725208119172, "accessLevel": "EDITOR"}'

Example response:

{

    "resultCode": 0,

    "result": {

        "id": "AAAFeF82FOeE",

        "type": "USER",

        "userId": 1539725208119172,

        "email": "jane.doe@smartsheet.com",

        "name": "Jane Doe",

        "accessLevel": "EDITOR"

    },

    "message": "SUCCESS"

}

Share (with Groups) to Many

Shares a Sheet or Workspace to the users specified.

Method

POST /sheet/{sheetId}/multisharewithgroups

POST /workspace/{workspaceId}/multisharewithgroups

POST /report/{reportId}/multisharewithgroups

Access Scope

SHARE_SHEETS (when working with Sheets)

ADMIN_WORKSPACES (when working with Workspaces)

Headers

Content-Type: application/json

Request Body

A MultiShareWithGroups object containing ShareWithGroups objects limited to the following attributes:

  • type (string)
  • when type is "USER": userId or email
  • when type is "GROUP": groupId

Parameters

    sendEmail

    (optional)

Either "true" or "false" to  indicate whether or not to notify the user by email. Default is false.

Returns

Result object containing array of ShareWithGroups objects that were created.  Users and groups to whom the Sheet or Workspace that had previously been shared remain unchanged and are not included in the return value.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/multisharewithgroups?sendEmail=true \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X POST \

-d '{"shares": [{"type": "USER", "userId": 1539725208119172}, {"type": "GROUP", "groupId": 2331373580117892}],"subject":"My new Smartsheet","message":"I have shared a Smartsheet with you. Please review it for the latest updates", "accessLevel":"ADMIN","ccMe":false}'

Example response:

{

    "resultCode": 0,

    "result": [

        {

            "id": "AQAISF82FOeE",

            "type": "GROUP",

            "groupId": 2331373580117892,

            "name": "Group 1",

            "accessLevel": "ADMIN"

        },

        {

            "id": "AAAFeF82FOeE",

            "type": "USER",

            "userId": 1539725208119172,

            "email": "jane.doe@smartsheet.com",

            "name": "Jane Doe",

            "accessLevel": "ADMIN"

        }

    ],

    "message": "SUCCESS"

}

Update Share (with Groups)

Updates the access level of a user or group for the specified Sheet or Workspace.

Method

PUT /sheet/{sheetId}/sharewithgroups/{shareId}

PUT /workspace/{workspaceId}/sharewithgroups/{shareId}

PUT /report/{reportId}/sharewithgroups/{shareId}

Access Scope

SHARE_SHEETS (when working with Sheets)

ADMIN_WORKSPACES (when working with Workspaces)

Headers

Content-Type: application/json

Request Body

Share object limited to the following attributes:

  • accessLevel (string)

Returns

Result object containing the modified ShareWithGroups object.

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/sharewithgroups/{shareId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-H "Content-Type: application/json" \

-X PUT \

-d '{"accessLevel": "VIEWER"}'

Example response:

{

    "resultCode": 0,

    "result": {

        "id": "AAAFeF82FOeE",

        "type": "USER",

        "userId": 1539725208119172,

        "email": "jane.doe@smartsheet.com",

        "name": "Jane Doe",

        "accessLevel": "VIEWER"

    },

    "message": "SUCCESS"

}

Delete Share (with Groups)

Deletes the Share.

Method

DELETE /sheet/{sheetId}/sharewithgroups/{shareId}

DELETE /workspace/{workspaceId}/sharewithgroups/{shareId}

DELETE /report/(reportId)/sharewithgroups/{shareId}

Access Scope

SHARE_SHEETS (when working with Sheets)

ADMIN_WORKSPACES (when working with Workspaces)

Returns

Result object

Example request:

curl https://api.smartsheet.com/1.1/sheet/{sheetId}/sharewithgroups/{shareId} \

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

    "message": "SUCCESS",

    "resultCode": 0

}

Server Information

For developer convenience, the Smartsheet API exposes an operation, GET /serverinfo, that provides application constants.

ServerInfo Object

supportedLocales

array of strings

A list of all Smartsheet-supported locales.

formats

a FormatTables object

Definition of format lookup tables used in Column, Row, and Cell “format” property.  See Formatting section.

Methods

Get Server Info

Retrieves server constants.

Method

GET /serverinfo

Access Scope

None required (may be called unauthenticated)

Returns

A ServerInfo object

Example request:

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

Example response:

(too long to list in its entirety)

{

        "supportedLocales": [ ... ],

        "formats": { ... }

}

Formatting

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

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

Row & Column Format

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

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

Format Descriptor

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

Format Descriptor Element #

Format Style

FormatTables Lookup Table Property

0

Font family

fontFamily

1

Font size

fontSize

2

Bold

bold

3

Italic

italic

4

Underline

underline

5

Strikethrough

strikethrough

6

Horizontal alignment

horizontalAlign

7

Vertical alignment

verticalAlign

8

Text color

color

9

Background color

color

10

Taskbar color

color

11

Currency

currency

12

Decimal count

decimalCount

13

Thousands separator

thousandsSeparator

14

Number format

numberFormat

15

Text wrap

textWrap

NOTE: Formats which have not been explicitly set are omitted in the descriptor string.  For example, a cell which has been set to bold and italic, but has no other formats applied to it, would have a format descriptor of ",,1,1,,,,,,,,,,,,".

 

As a convenience, the FormatTables object contains a “defaults” property which is a format descriptor that describes which formats the Smartsheet web application displays for unset formats.  Your application can use these values to display unformatted cells identically to the Smartsheet web application.

FormatTables Object

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

Indexes and their values are guaranteed never to change or be removed for a given major API version.  However, new values could potentially be added to the ends of lookup tables.

Because of this possibility, your code should handle the case where a cell might contain a format index value greater than the size of a lookup table your app has loaded.  Your application should check for that case and reload the format tables if necessary.

defaults

string

A format descriptor where each element describes the formats the Smartsheet web application displays for format values that have not been set.

fontFamily

array of FontFamily objects

Font families with additional font information

fontSize

array of strings

Font sizes in points

bold

array of strings

Possible values: "none", "on"

italic

array of strings

Possible values: "none", "on"

underline

array of strings

Possible values: "none", "on"

strikethrough

array of strings

Possible values: "none", "on"

horizontalAlign

array of strings

Horizontal alignment values (left, center, right).  NOTE: "default" is the default value; for text/number columns, default alignment equates to left for text values, and right for numeric values.

verticalAlign

array of strings

Vertical alignment values (top, middle, bottom).  NOTE: "default" is the default value, which is equivalent to top.

color

array of strings

Color hex values.  NOTE: "none" is the default value for all colors.  Applications will need to handle this value and use app-defined colors (typically this is Black for text color and White for background color)

currency

array of Currency objects

Currency codes and symbols

decimalCount

array of strings

All allowed decimal count values

thousandsSeparator

array of strings

Possible values: "none", "on"

numberFormat

array of strings

Possible values: "none", "NUMBER", "CURRENCY", "PERCENT"

textWrap

array of strings

Possible values: "none", "on"

FontFamily Object

name

string

The name of the font family (e.g. "Arial")

traits

array of strings

Platform-independent traits of this font family .  Current values may be one of "serif" or "sans-serif".

Currency Object

code

string

The ISO 4217 currency code (e.g. "EUR")

symbol

string

The currency symbol (e.g. "€")

Other Objects

Result Object

Object returned for all PUT, POST and some other operations.

resultCode

integer

0 if successful

message

string

xxxxxx

result

Object

The object that was created or updated, Optional.

version

integer

the new version of a sheet. Currently only available on select operations.

Email Object

An object for sending an email

to

array

An array of strings as email addresses to send to.  Optional, but at least one “to” and/or “toGroups” value is required.

toGroups

array

An array of group ids to send to.  Optional, but at least one “to” and/or “toGroups” value is required.

subject

string

The subject of the email, optional.

message

string

The message of the email, optional

ccMe

boolean

A flag to indicate whether to copy the sender or not. Optional, defaults to false

RowEmail Object

Extends Email

An object for sending a row by email.

includeAttachments

boolean

A flag to indicate whether or not to include attachments in the email.

includeDiscussions

boolean

A flag to indicate whether or not to include discussions in the email.

SheetEmail Object

Extends Email

An object for sending a sheet by email.

format

string

Can either be "PDF" or "EXCEL"

formatDetails

FormatDetails

Currently, only the "paperSize" attribute can be set on the FormatDetails object. paperSize can be one of: LETTER,LEGAL,WIDE,ARCHD,A4,A3,A2,A1,A0

Link Object

A link can be a cell link, a sheet link, or a url link, as part of the data for a cell.

NOTE: This object is deprecated as of the 8/23/2014 API release.  It has been replaced by the Hyperlink and CellLink objects.

type

string

one of:

URL

SHEETLINK

CELLLINK

url

string

when type is URL, this will have the URL value. When type is SHEETLINK, this is the permalink to the sheet.

sheetId

number

when type is SHEETLINK or CELLLINK, this is the id of the sheet that has been linked to.

columnId

number

when type is CELLLINK, this is the columnId of cell that has been linked to.

rowId

number

when type is CELLLINK, this is the rowId of cell that has been linked to

Hyperlink Object

Represents a cell hyperlink to a URL or sheet.

If the sheet or report that is linked to was deleted, this object may be empty (i.e. all values null).

url

string

When this hyperlink is a URL link, this will be the URL value.

When this hyperlink is a sheet/report link (i.e. sheetId or reportId is non-null), this will be the permalink to the sheet.

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.

CellLink Object

Represents a cell link to a cell in a different sheet.

If status is not "OK" (i.e. there is a problem with the link), any or all of sheetId, rowId, or columnId may be null.

status

string

One of:

  • 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

The sheet the linked cell belongs to

rowId

number

The row of the linked cell

columnId

number

The column of the linked cell

sheetname

string

The column of the linked cell

AutoNumberFormat Object

An object that describes how the the System Column type of "AUTO_NUMBER" is auto-generated

prefix

string

The prefix. Can include the date tokens {YY}, {YYYY}, {MM}, {DD}

suffix

string

The suffix. Can include the date tokens {YY}, {YYYY}, {MM}, {DD}

fill

string

Must be 0 - 10 "0" characters. Indicates zero-padding

startingNumber

number

The starting number for the auto-id.

 of