API Documentation

Smartsheet Developers

API Documentation

_____________________________

API Fundamentals

Overview

Rate Limiting

Errors

Authentication

Access Levels

Column Types

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

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

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

Columns

Column Object

Modify Column

Delete Column

Rows

Row Object

Get Row

Modify Row

Delete Row

Send Row

Row Cells

Cell Object

Cell History Object

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

Discussions

Discussion Object

Get Discussion

Create 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

Update User

Delete User

List All Sheets

Search

Search Result Object

SearchResultItem Object

Search Everything

Search Sheet

Sharing

Share Object

Get Shares

Get Share

Share to One

Share to Many

Update Share

Delete Share

Other Objects

Result Object

Email Object

RowEmail Object

SheetEmail Object

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

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

2000

Invalid username and/or password.

2001

Your account is locked out.

2002

Invalid email address

2003

Your account is currently locked out. Please contact Smartsheet support at support@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.

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.

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.

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.

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.

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

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)

comma-delimited list of access scopes to which you are asking the user to grant access

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,WRITE_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

/workspaces

/folders

/templates

/sheets

/columns

/rows

/attachments

/discussions

/comments

/users

/search

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.

Workspaces

Workspace Object

id

number

workspace ID

name

string

workspace name

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.

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

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

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

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.

version

number

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

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

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

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

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 either "application/pdf" or "application/vnd.ms-excel"

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

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

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, Move 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

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)

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.

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, and, optionally, strict.  See Column Types 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.

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

You can retrieve a list of available Reports (see Home) but we do not currently support creating, sharing, or accessing Reports.

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

Methods

Modify Column

Allows you to move, rename, change column type or column dropdown values. 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 /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)

Returns

Result object containing Column object that was modified.

Example request:

curl https://api.smartsheet.com/1.1/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 /column/{columnId}

Access Scope

ADMIN_SHEETS

Returns

Result object.

Example request:

curl https://api.smartsheet.com/1.1/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

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.

Methods

Get Row

Gets a row by its Id.

Method

GET /row/{rowId}

Access Scope

READ_SHEETS

Parameters

    include

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

discussions

attachments

columns

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.

Returns

Result object for the ID provided.

Example request:

curl https://api.smartsheet.com/1.1/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 /row/{rowId}

Access Scope

WRITE_SHEETS

Request Body

A RowWrapper object.  The “expanded” property and/or one of the position properties below may be set.

  • 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/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 /row/{rowId}

Access Scope

WRITE_SHEETS

Returns

Result object.

Example request:

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

-H "Authorization: Bearer ACCESS_TOKEN" \

-X DELETE

Example response:

{

   "message": "SUCCESS",

   "resultCode": 0

}

Send Row

Sends a row via email.

Method

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

formula

string

the formula for a cell, if set.

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.

Update Row Cells

Updates the values of the Cells in a Row.

Method

PUT /row/{rowId}/cells

Access Scope

WRITE_SHEETS

Request Body

An array of Cells to be updated.  

Cells must have the following attributes set: columnId, value, and, optionally, strict.  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 or cell links 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.

Method

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/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 /row/{rowId}/attachments

Access Scope

READ_SHEETS

Returns

A List of Attachment objects.

Example request:

curl https://api.smartsheet.com/1.1/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 or BOX_COM)

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.

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 /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/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/row/{rowId}/attachments

https://api.smartsheet.com/1.1/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.

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.

Method

POST /sheet/{sheetId}/attachments

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") or a Box.com URL (attachmentType "BOX_COM").  

NOTE: when the attachment type is BOX_COM, the mimeType will be derived by the file extension specified on the "name".

NOTE: the following attachmentSubTypes are valid for GOOGLE_DRIVE attachments "DOCUMENT", "SPREADSHEET", "PRESENTATION", "PDF", "DRAWING".

 

Method

POST /sheet/{sheetId}/attachments

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.

Method

DELETE /attachment/{attachmentId}

Access Scope

WRITE_SHEETS

Returns

Result object.

Example request:

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

-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

Methods

Get Discussion

Gets a Discussion by its ID.

Method

GET /discussion/{discussionId}

Access Scope

READ_SHEETS

Returns

Discussion object for the ID provided.

Example request:

curl https://api.smartsheet.com/1.1/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 /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

}

Add Comment

Adds a Comment to a Discussion.

Method

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/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 /discussion/{discussionId}/attachments

Access Scope

READ_SHEETS

Returns

A List of Attachment objects.

Example request:

curl https://api.smartsheet.com/1.1/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 /comment/{commentId}

Access Scope

READ_SHEETS

Headers

Content-Type: application/json

Returns

A Comment object.

Example request:

curl https://api.smartsheet.com/1.1/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 /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/comment/{commentId} \

-H "Authorization: Bearer ACCESS_TOKEN"\

-X 'DELETE'

Example response:

{

   "result":"SUCCESS",

   "code" : 0

}

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)

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 first name

Methods

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

List All Users

Lists all users in the organization.

Method

GET /users

Access Scope

ADMIN_USERS

Returns

Array of  User objects.

Example request:

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

-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)
  • firstName (optional)
  • lastName (optional)
  • admin (optional, boolean)
  • licensedSheetCreator (optional, boolean)
  • resourceManager (optional, boolean)

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

}

Update User

Updates a user in the organization.

Method

PUT /user/{userIId}

Access Scope

ADMIN_USERS

Headers

Content-Type: application/json

Request Body

User object containing at least one of the following attributes:

  • admin (boolean)
  • licensedSheetCreator (boolean)

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 a list of all sheets in an 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

    }

]

Search

Search Result Object

totalCount

number

total number or results

results

array of SearchResultItems

Methods

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

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

Share Object

id

number

user ID

name

string

user name, if user is also a contact

accessLevel

string

user's permissions on workspace

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.

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

}

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.

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.

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

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