Smartsheet API 2.0

Updated 2021-04-06

Overview

To see Smartsheet’s current developer documentation, go to and bookmark Smartsheet API Reference, which now uses OpenAPI for API definitions and object modeling. For feedback, use Smartsheet Community for API Developers.

Introduction

Click the corresponding tab above to see sample code in the language of your choice. For more detail, see SDKs and Sample Code)

# The cURL code samples included in this API documentation demonstrate
# how to execute operations using the command line data transfer
# tool cURL: https://curl.haxx.se/.

// The Node.js code samples included in this API documentation demonstrate
// how to execute operations using the Smartsheet JavaScript
// SDK: https://github.com/smartsheet-platform/smartsheet-javascript-sdk.

// The C# code samples included in this API documentation demonstrate
// how to execute operations using the Smartsheet
// C# SDK: https://github.com/smartsheet-platform/smartsheet-csharp-sdk.

// The Java code samples included in this API documentation demonstrate
// how to execute operations using the Smartsheet
// Java SDK: https://github.com/smartsheet-platform/smartsheet-java-sdk.

# The Python code samples included in this API documentation demonstrate
# how to execute operations using the Smartsheet Python SDK:
# https://github.com/smartsheet-platform/smartsheet-python-sdk.

# The Ruby code samples included in this API documentation demonstrate
# how to execute operations using the Smartsheet
# Ruby SDK: https://github.com/smartsheet-platform/smartsheet-ruby-sdk.

Smartsheet API 2.0 allows you to programmatically access and manage your organization's Smartsheet data and account information. The API allows you to do the following:

• Read and update sheets
• Manage folders and workspaces
• Administer user accounts and organization account

You can view code examples in the programming language of your choice by clicking the corresponding tab in the dark-blue area in the rightmost pane. Each tab corresponds to a Software Development Kit (SDK) that Smartsheet provides to make working in that programming language easier. See SDKs and Sample Code.

How Do I Start?

This documentation provides two Getting Started tutorials that walk you through making your first API call and interpreting the response to a GET /sheet request. You may also want to bookmark or note the following resources:

• Smartsheet Developer Portal: If registering, use a different email address from your paid Smartsheet account so you can test the API and make API calls
• Developer Newsletter (subscribe while at the Developer Portal using the "Get Developer Updates" form)
• StackOverflow using the "smartsheet-api" tag
• Contact us at help.smartsheet.com/contact
• 10000ft API documentation
• Review the Developer Program Agreement

HTTP and REST

RESTful Architecture

The REST URL structure follows typical resource-oriented conventions.

To get a list of sheets, use the following:

GET https://api.smartsheet.com/2.0/sheets

This returns a list of Sheet objects, where each sheet has an id attribute.

To get details on the sheet with id 123456, use the following:

GET https://api.smartsheet.com/2.0/sheets/123456

This Id pattern is repeated throughout the API. Columns, rows, cells, comments, attachments, or any other data element have a unique Id.

If you don't want to make raw HTTP calls, Smartsheet also has several Software Development Kits (SDKs) that provide a higher level interface for popular programming languages. For more information, see SDKs and Sample Code.

HTTP Verbs

Call the API using the following standard HTTP methods:

• GET (to retrieve an object or multiple objects in a specific category)
• POST (to create)
• PUT (to modify)
• DELETE

HTTP Status Codes

Smartsheet uses a combination of HTTP status codes and custom error codes with a descriptive message in JSON-formatted Error objects to give you a more complete picture of what has happened with your request.

HTTP status code	Meaning	To Retry or Not to Retry?
2xx	Request was successful. Example: 200 Success	--
4xx	A problem with request prevented it from executing successfully.	Never automatically retry the request. If the error code indicates a problem that can be fixed, fix the problem and retry the request.
5xx	The request was properly formatted, but the operation failed on Smartsheet's end.	In some scenarios, requests should be automatically retried using exponential backoff.

For example, doing a GET on a non-existent sheet at https://api.smartsheet.com/2.0/sheets/123456 results in an HTTP status code of 404, indicating the resource was not found.

{
    "errorCode": 1006,
    "message": "Not Found"
}

Some errors may contain a detail attribute set to an object with additional error details that may be useful in programmatically handling the error. If so, it is noted in the specific API operation for which the error may occur.

HTTP Headers

Unless otherwise specified, all API endpoints expect request body data to be in JSON, and the response body data is returned as JSON.

The following HTTP request headers may be required, depending on the operation and endpoint being invoked:

Header	Definition	Example
Authorization	Required for all endpoints, except for POST /token. The access token.	Bearer ll352u9jujauoqz4gstvsae05
Content-Type	Required for POST and PUT requests. Defines the structure for the response.	application/json
Assume-User	Optional. Allows an admin to act on behalf of, or impersonate, the user to make API calls. The email address used to identify the user must be URI-encoded.	jane.doe%40smartsheet.com

Query Strings

Example request: list sheets with query strings

curl https://api.smartsheet.com/2.0/sheets?include=attachments,source&includeAll=true \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  queryParameters: {
    include: "attachments",
    include: "source",
    includeAll: true
  }
};

// List sheets
smartsheet.sheets.listSheets(options)
    .then(function(response) {
        console.log(response);
    })
    .catch(function(error) {
        console.log(error);
    });

PaginatedResult<Sheet> sheets = smartsheet.SheetResources.ListSheets(
  new SheetInclusion[] { SheetInclusion.SOURCE },
  new PaginationParameters(
    true,           // includeAll
    null,           // int pageSize
    null)           // int page
);

// Specify pagination parameter 'includeAll'
PaginationParameters page_params = new PaginationParameters()
  .setIncludeAll(true);

// Specify `include` parameters
EnumSet include_params = EnumSet.of(SourceInclusion.SOURCE);

// List Sheets with pagination and include parameters
PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(include_params, page_params, null);

response = smartsheet_client.Sheets.list_sheets(include="attachments,source", include_all=True)
sheets = response.data

response = smartsheet.sheets.list(params: {include:"attachments,source", includeAll:true })
sheets = response

Many API calls can be modified by including one or more of these common query strings:

Query Parameter	Type	Description	More Info
allowPartialSuccess	Boolean	If true, allows bulk operations to process even if one or more operations are invalid for some reason, for example, allowPartialSuccess=true.	Bulk Operations
include or exclude	String	When applicable for a specific object, various include or exclude parameters are available, for example, include=format.	Object reference or Formatting
includeAll	Boolean	If true, includes all results, for example, includeAll=true.	Paging
numericDates	Boolean	If true, allows you to input or receive dates in numeric format, for example, numericDates=true.	Dates and Times
page	String	Specifies which page to return, for example, page=4.	Paging
pageSize	Number	Specifies the maximum number of items to return per page, for example, pageSize=25.	Paging

Authentication and Access Tokens

Example request: authentication and access tokens

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

// Set the access token
var client = require('smartsheet');
var smartsheet = client.createClient({accessToken:'ll352u9jujauoqz4gstvsae05'});

// Get current user
smartsheet.users.getCurrentUser()
    .then(function(userProfile) {
        console.log(userProfile);
    })
    .catch(function(error) {
        console.log(error);
    });

// Set the access token
String accessToken = "ll352u9jujauoqz4gstvsae05";

SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(accessToken).Build();

// Get current user
UserProfile userProfile = smartsheet.UserResources.GetCurrentUser();

// Set the access token
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken("ll352u9jujauoqz4gstvsae05").build();

// Get current user
UserProfile userProfile = smartsheet.userResources().getCurrentUser();

# Create base client object and set the access token
smartsheet_client = smartsheet.Smartsheet('ll352u9jujauoqz4gstvsae05')

# Get current user
user_profile = smartsheet_client.Users.get_current_user()

require 'smartsheet'

# Add your token to the config.json file
{
  "token": "ll352u9jujauoqz4gstvsae05",
  "sheet_id": "5091283781476228"
}

Example response

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

The Smartsheet API uses OAuth 2.0 for authentication and authorization. An HTTP header containing an access token is required to authenticate each request.

• To familiarize yourself with the API, you can generate a raw token. See Raw Token Requests.
• For additional security and as a recommended best practice, you should build an integration using OAuth 2.0. During the OAuth process, you will generate several API keys and, ultimately, each user will generate a unique access token.

Raw Token Requests

If you want to get started quickly, or are developing a standalone application that can run with your credentials, follow these instructions:

1. Click the "Account" button in the upper-right corner of the Smartsheet screen, and then click "Personal Settings".
2. Click the "API Access" tab.
3. Click the "Generate new access token" button to obtain an access token.

The access token must be sent with every API call in an HTTP authorization header (except for the requests to Get Access Token or Refresh Access Token). Once you have an access token, include it in the Authorization header for every request you make:

Authorization: Bearer ll352u9jujauoqz4gstvsae05

The header name is Authorization and the value of the header is Bearer ll352u9jujauoqz4gstvsae05. Since the access token is being transmitted in clear text, all API calls are done over HTTPS.

Adding Security by Using OAuth

If your application requires users to be able to login with their own account, you must implement the full OAuth flow.

At a high level, this involves the following steps:

1. Register as a Developer with Smartsheet so you can get access to the Developer Tools menu.
2. Register your app to get both a clientId and client secret, which you'll need to store securely. Some best practices suggestions for security are below.
3. Go through the steps in the Third-party App Development section once you are ready to request authorization.

Security Best Practices

The following provides some best practices to consider when working with the Smartsheet API and any API keys, tokens, or other sensitive information.

Source Code and Version control

Never commit API keys to accessible version control systems like GitHub or BitBucket. Instead, you should:

• Use an app configuration tool suitable for deploying secrets to your app, or
• Use a config file outside of source control, or
• Use environment variables set outside of source control.

If you have mistakenly deployed API keys to a publicly accessible location such as GitHub, then you should immediately revoke those API keys, revise your application to use a preferred method of key deployment, and then generate new keys.

If you need to store API keys in a database, consider the following protections:

• Restrict access so API keys are only readable by the owner of the object
• Restrict read privileges to the database table
• Make sure your database or the disk the database is on is set to encrypt data at rest

API Key Management

If you've committed code to a repository before implementing these security best practices, here are some steps to resecure your API keys.

For raw tokens:

1. Revoke token
2. Create a new token

If using OAuth for an integration:

• Work through the steps for Third-party App Development to regenerate client secrets, auth codes, and tokens.

Dates and Times

The Smartsheet API returns all dates and times in the UTC time zone in ISO-8601 format, that is, YYYY-MM-DDTHH:MM:SSZ. If you are specifying a date and time, you should also send that information in ISO-8601 format. If a date/time needs to be displayed to an end-user in their local time zone, you must do the conversion using the user's time zone, which you can obtain by getting the current user.

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

Filtering

You cannot create or update filters using the API; however, you can query which rows have been filtered out and you can get filter definitions.

For details, see Filters object.

Formulas

Formulas are processed per cell in the UI. Use the Cell object to manipulate formulas via the API.

For requests, use Update Rows to add or update the formula in a cell.

For response payloads, formulas (when present) are returned whenever the Cell object is returned, so for example, GET /sheets/(id) returns the Cell object for each cell and that object contains a formula value when the cell contains a formula.

Object Details vs List Summaries

Many of the List All commands, for example, GET /sheets, return only an abbreviated object for each object returned. For full details, read a single item, such as GET /sheets/{sheetId}. In many cases, you can refine the exact object properties to be returned by using include and exclude query parameters.

The JSON representation of the objects returned from the List All REST endpoints will only include a subset of the properties documented here. However, the objects returned from the Java and C# SDKs will represent the omitted properties with NULLs.

Sheets/Columns/Rows/Cells

Sheets are composed of rows, columns, and cells. A cell is identified by the Id of its row and column. The following table defines these terms and points you to places in this documentation where you can find more information:

UI Element	Description	More Info
sheet	A sheet can exist in a user's Home folder, in a folder, or in a workspace. It is comprised of columns, rows, and cells, and may optionally contain attachments or discussions.	Sheet object
column	A Column object defines the type of the column, but does not actually contain cells. The Column Id identifies the cells in a row.	Column object, Column types
row	A row is a component of a sheet or report. Each row is composed of a collection of cells, and may optionally contain attachments or discussions.	Row object
cell	A cell is a location within a sheet that may contain a value. A collection of cells comprises each row in a sheet.	Cell object, Cell reference

Versioning and Changes

Smartsheet will add new functionality and bug fixes to the API over time. Make sure that your code can handle new JSON properties gracefully. Also, make sure your code does not depend on the order in which JSON objects are returned, unless it is explicitly stated in this documentation.

When there is new functionality that is not compatible with existing code, say in the case of a new concept, Smartsheet increments the level to indicate the new feature can be ignored until you are ready to implement the code to work with the new level.

See also: Working with Complex Objects: Multi-contact or Multi-picklist

Working with Complex Objects: Multi-contact or Multi-picklist

New column types, such as MULTI_CONTACT_LIST and MULTI_PICKLIST, offer more complex ways to work with columns. Smartsheet has provided a backwards compatible way for these payloads to work with your existing integrations while also giving you a way to query for their content.

With either column type, there are two ways of receiving the response:

• If you do nothing to your code, column types will display as TEXT_NUMBER
• If you use the level query parameter as detailed below, column types will display as MULTI_CONTACT_LIST or MULTI_PICKLIST and return a complex object (aka a non-primitive type)

Smartsheet uses two indicators to help you discover changes in the return data for your API calls:

• level: a query parameter that is incremented when a new feature or column type is added
• version: each element in the Columns array is set to one of the following values:

Text	Multi-contact	Multi-picklist
0	1	2

You must use the level query parameter, for example level=2, to return a complex object with the new column type. Without the query parameter, the response will be backwards-compatible, that is a string.

Use the highest possible level for each endpoint, as in the following table:

Endpoint category	Level
Dashboards (referred to as Sights in the API)	4
Reports	3
Sheets	2

Working with Smartsheet Gov Accounts

Smartsheet Gov has "FedRAMP Authorized" status as part of Federal Risk and Authorization Management Program (FedRAMP). As an API developer working on a Smartsheet Gov account, you should be aware of the following differences from the standard API:

• The base URL for each API call is smartsheetgov.com instead of smartsheet.com. This documentation uses smartsheet.com in all examples.
• Smartsheetgov.com has a restriction on attachment types. Only the following attachment types are allowed: BOX_COM, FILE, GOOGLE_DRIVE, LINK, or ONEDRIVE.

• If you use a Smartsheet SDK, you need to modify the standard config file to point to smartsheetgov.com. There are instructions specific to each SDK on how to modify the config file at the following locations:

  • C# SDK
  • Java SDK
  • Node.js SDK
  • Python SDK
  • Ruby SDK

Getting Started

Make Your First API Call

Before you write any code, try executing API requests using a tool like cURL or Postman. By taking your code out of the equation, you can isolate troubleshooting to the raw request and response.

You must use an access token. See instructions at Authentication and Access Tokens. In the examples below, replace this sample token, "ll352u9jujauoqz4gstvsae05", with your actual token value.

To get a list of all your sheets, try the following command:

curl -X GET -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" "https://api.smartsheet.com/2.0/sheets"

In Postman, the request looks like this:

The JSON result should look something like this (after formatting):

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [{
    "id": 6141831453927300,
    "name": "My first sheet",
    "accessLevel": "ADMIN",
    "permalink": "https://app.smartsheet.com/b/home?lx=8enlO7GkdYSz-cHHVus33A",
    "createdAt": "2016-01-28T22:02:35Z",
    "modifiedAt": "2016-08-09T17:50:06Z"
  },
  {
    "id": 6141831453927300,
    "name": "Sheet shared to me",
    "accessLevel": "VIEWER",
    "permalink": "https://app.smartsheet.com/b/home?lx=8enlO7GkdYSz-cHHVus33A",
    "createdAt": "2016-01-28T22:02:35Z",
    "modifiedAt": "2016-08-09T17:50:06Z"
  }
    ]
}

How to Read a Sheet Response

Many Smartsheet API operations handle sheets, rows, columns, and cells. Each is identified by an Id and it is important to understand the relationship between these objects. Typically you loop through the columns to determine the Id of the columns you are interested in. Then you loop through the rows and contained cells to find actual values. The annotated sample response below illustrates these concepts by calling a very simple sheet called "Employee Roster".

Before you begin, you should already have an access token, which you used in the exercise above. Use the same access token for this walkthrough.

Step 1: The first thing you must have is a sheetId. To find a sheetId through the UI, with the sheet open, click "Sheet Actions" in the left toolbar and select "Properties". NOTE: use List Sheets if you want to do this programmatically.

Step 2: Copy the sheetId into the API call, GET /sheets, as below:

curl -X GET -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" "https://api.smartsheet.com/2.0/sheets/6141831453927300"

Step 3: The sample request and response are displayed below. NOTE: while JSON doesn't have a comment feature, this sample uses comments to help you identify the objects in the response.

{
  "id": 6141831453927300,                 // This is the Id of the entire sheet
  "name": "My first sheet",
    "columns": [{                         // Each Column object associates column
                                          // Id to title and defines the
                                          // column details

      "id": 2517104256673668,             // Column Id identifies cells on a row
      "index": 0,
        "title": "Name",                  // This is the column name as seen
                                          // in the UI
      "type": "TEXT_NUMBER",
      "primary": true,
      "width": 150
    },
    {
      "id": 7020703884044164,
      "index": 1,
      "title": "EmployeeId",
      "type": "TEXT_NUMBER",
      "width": 150
    }
  ],
  "rows": [{                              // A Row object
    "id": 564480076736388,                // Use the row Id to make updates
    "rowNumber": 1,
    "expanded": true,
    "createdAt": "2017-05-12T16:52:38Z",
    "modifiedAt": "2017-05-22T20:40:14Z",
      "cells": [{                         // Each row contains an array of cells,
                                          // which have the actual content

        "columnId": 2517104256673668,     // The column Id can be interpreted by
                                          // looking at the array of column
                                          // definitions above. That tells you
                                          // this is the "Name" column

      "value": "John Doe",            
        "displayValue": "John Doe"      
    },
    {
      "columnId": 7020703884044164,
      "value": 12345,                     // Actual cell value
      "displayValue": "12,345"            // How the cell value is displayed
                                          // in the UI
    }
    ]},
    {
      "id": 5068079704106884,
      "rowNumber": 2,
      "siblingId": 564480076736388,
      "expanded": true,
      "createdAt": "2017-05-12T16:52:38Z",
      "modifiedAt": "2017-05-22T20:40:14Z",
      "cells": [{
        "columnId": 2517104256673668,
        "value": "Jane Roe",
        "displayValue": "Jane Roe"
      },
      {
        "columnId": 7020703884044164,
        "value": 67890,
        "displayValue": "67890"
      }
      ]
    }
  ]
}

This core hierarchy of Sheet > Column > Row > Cell is essential to working with the Smartsheet API. As your user's sheets grow in complexity, the responses do too. This walkthrough has given you some navigational aid in finding the right value to plug into your API calls. Use the API Reference and the example language tabs to learn more.

SDKs and Sample Code

Install the SDK

# The cURL code samples included in this API documentation demonstrate
# how to execute operations using the command line data transfer
# tool cURL: https://curl.haxx.se/.

npm install smartsheet

// In the Visual Studio Package Manager Console
Install-Package smartsheet-csharp-sdk

// Add the SDK as a dependency in your project
<dependency>
  <groupId>com.smartsheet</groupId>
  <artifactId>smartsheet-sdk-java</artifactId>
  <version>2.2.0</version>
</dependency>

$ pip install smartsheet-python-sdk

# Add this line to your application's Gemfile
gem 'smartsheet', '>= 1.0.0'

# And then execute
$ bundle

Load the client

# Click the corresponding language tab when using the SDK for that language.

// Initialize client SDK
var client = require('smartsheet');
var smartsheet = client.createClient({ accessToken: ll352u9jujauoqz4gstvsae05 });

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

// Initialize client
String accessToken = "ll352u9jujauoqz4gstvsae05";

SmartsheetClient smartsheet = new SmartsheetBuilder()
  .SetAccessToken(accessToken)
  .Build();

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

// Initialize client
String accessToken = "ll352u9jujauoqz4gstvsae05";

Smartsheet smartsheet = new SmartsheetBuilder()
  .setAccessToken(accessToken)
  .build();

import smartsheet

# Initialize client
smartsheet_client = smartsheet.Smartsheet(access_token)

# Make sure we don't miss any errors
smartsheet_client.errors_as_exceptions(True)

require 'smartsheet'
require 'logger'

logger = Logger.new(STDOUT)
logger.level = Logger::INFO

# Initialize client
smartsheet = Smartsheet::Client.new(token: 'll352u9jujauoqz4gstvsae05', logger: logger)

# Example call
response = smartsheet.sheets.list
sheets = response[:data]

# Return is a Ruby Hash as below, though this document
# displays a JSON example to accommodate the multiple tabs
{
  :id=>0123456789012345,
  :name=>"Expense Report May 2017",
  :access_level=>"VIEWER",
  :permalink=>"https://app.company.com",
  :created_at=>"2016-12-08T21:14:43Z",
  :modified_at=>"2017-08-20T02:47:41Z"
}

Smartsheet has Software Development Kits (SDKs) providing a higher level interface for several languages.

Language	SDK	Sample application
C#	smartsheet-csharp-sdk	csharp-read-write-sheet
Java	smartsheet-java-sdk	java-read-write-sheet
Node.js	smartsheet-javascript-sdk	node-read-write-sheet
Python	smartsheet-python-sdk	python-read-write-sheet
Ruby	smartsheet-ruby-sdk	ruby-read-write-sheet

In addition to the sample application provided for each SDK, you can always view code examples in this document by clicking the corresponding tab in the dark-blue area in the rightmost pane.

To use an SDK for development work, follow the instructions in the SDK readme to download and install the SDK. Then download the sample app and run it. Once you've run the sample application, you can clone it and use the structure it provides to start building your own applications.

Permission Levels

Access Levels

Sheets, templates, and workspaces have 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:

Value	Description
ADMIN	The user can edit and share the resource, and can alter the structure of the resource as well.
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.
OWNER	The user has complete control over the resource.
VIEWER	The user has read-only access to the resource.

Assume User

Example: assume user

curl https://api.smartsheet.com/2.0/sheets \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Assume-User: jane.doe%40smartsheet.com" \

// Set options
var options = {
  assumeUser: "jane.doe@smartsheet.com"
  };

// List Sheets
smartsheet.sheets.listSheets(options)
  .then(function(sheetList) {
      console.log(sheetList);
  })
  .catch(function(error) {
      console.log(error);
  });

SmartsheetClient smartsheet = new SmartsheetBuilder()
  .SetAccessToken(accessToken)
  .SetAssumedUser("jane.doe@smartsheet.com")
  .Build();

smartsheet.setAssumedUser("jane.doe@smartsheet.com");

smartsheet_client.assume_user("jane.doe@smartsheet.com")

smartsheet.sheets.list(
  header_override: {:'Assume-User' => CGI::escape('jane.doe@smartsheet.com')}
)

Allows an admin to act on behalf of, or impersonate, the user to make API calls. You might do this to troubleshoot a user problem or cover for vacations and sick time. As with cURL, the email address used to identify the user must be URI-encoded.

An admin cannot impersonate another admin.

Third-party App Development

Apps connect to Smartsheet using OAuth 2.0 to authenticate and authorize users. If you are building an app, this documentation will walk you through the steps you need to authenticate your users. The Smartsheet SDKs contain APIs for OAuth 2.0.

First Steps

Before you can start using OAuth 2.0 with your app, Smartsheet needs the following information:

1. You must register with Smartsheet to get a developer account*. The developer account gives you access to "Developer Tools", which is where you manage your app.
2. In "Developer Tools", complete your developer profile. This profile is public and anyone can access it to learn about you and your apps.
3. In "Developer Tools", register your app so Smartsheet can assign a client Id and a client secret to the app.
4. Review the list of access scopes. You'll need to choose which ones your app needs to get to a user's Smartsheet data, and then ask the user to consent to that access.

After you've worked through these steps, you'll be ready to implement the OAuth Flow.

*Review the Developer Program Agreement.

Open Developer Tools

1. Log in to Smartsheet with your developer account.
2. Click the "Account" button in the upper-right corner of your Smartsheet screen, and then click "Developer Tools".
3. Do one of the following:
   • If you need to register an app, click "Create New App".
   • If you need to manage an app, click "view/edit" for the app.

Register Your App Using Developer Tools

1. Log in to Smartsheet with your developer account.
2. Click the "Account" button in the upper-right corner of your Smartsheet screen, and then click "Developer Tools".
3. In the "Create New App" form, provide the following information:
   • Name: the name the user sees to identify your app
   • Description: a brief description intended for the user
   • URL: the URL to launch your app, or the landing page if not a web app
   • Contact/support: support information for the user
   • Redirect URL: also known as a callback URL. The URL within your application that will receive the OAuth 2.0 credentials

After you click "Save", Smartsheet assigns a client Id and secret to your app. Make a note of these Ids for the next steps; however, you can always look them up again in "Developer Tools".

Access Scopes

To access a user's Smartsheet data, your application must explicitly ask the user for permission. You do this by using access scopes, which enable your app to communicate to the user what type of operations it is performing. Access scopes do not override existing access-level restrictions. For example, having the access scope of WRITE_SHEETS does not allow your app to update a sheet on which the user has VIEWER access level.

The access scopes are as follows:

Access Scope	Description
ADMIN_SHEETS	Modify sheet structure, including column definition, publish state, etc.
ADMIN_SIGHTS	Modify dashboards structure.
ADMIN_USERS	Add and remove users from your Smartsheet organization account; create groups and manage membership.
ADMIN_WEBHOOKS	Create, delete, and update webhooks; get all webhooks; reset shared secret.
ADMIN_WORKSPACES	Create and manage workspaces and folders, including sharing.
CREATE_SHEETS	Create new sheets.
CREATE_SIGHTS	Create new dashboards.
DELETE_SHEETS	Delete sheets.
DELETE_SIGHTS	Delete dashboards.
READ_CONTACTS	Retrieve contacts.
READ_SHEETS	Read all sheet data, including attachments, discussions, and cell data.
READ_SIGHTS	Read all dashboards data.
READ_USERS	Retrieve users and groups for your Smartsheet organization account.
SHARE_SHEETS	Share sheets, including sending sheets as attachments.
SHARE_SIGHTS	Share dashboards.
WRITE_SHEETS	Insert and modify sheet data, including attachments, discussions, and cell data.

OAuth Flow

Your app must implement a 3-legged OAuth flow to retrieve an access token it can use to access Smartsheet data on behalf of an end user. The following diagram has an overview of the OAuth flow:

Request an Authorization Code

Request an authorization code:

curl 'https://app.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE' \
-X GET

const qs = require('querystring');

function authorizeURL(params) {
  const authUrl = 'https://app.smartsheet.com/b/authorize';
  return `${authUrl}?${qs.stringify(params)}`;
}

const authorizationUri = authorizeURL({
  response_type: 'code',
  client_id: '1samp48lel5for68you',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'CREATE_SHEETS WRITE_SHEETS',
});

// Initial page redirecting to Smartsheet
app.get('/auth', (req, res) => {
  console.log(authorizationUri);
  res.redirect(authorizationUri);
});

OAuthFlow oauth = new OAuthFlowBuilder()
  .SetClientId("1samp48lel5for68you")
  .SetClientSecret("sxouqll7zluvzmact3")
  .SetRedirectURL("http://localhost:3000/callback")
  .Build();

string url = oauth.NewAuthorizationURL
(
  new Smartsheet.Api.OAuth.AccessScope[]
  {
    Smartsheet.Api.OAuth.AccessScope.READ_SHEETS,
    Smartsheet.Api.OAuth.AccessScope.WRITE_SHEETS,
    Smartsheet.Api.OAuth.AccessScope.SHARE_SHEETS,
    Smartsheet.Api.OAuth.AccessScope.DELETE_SHEETS,
    Smartsheet.Api.OAuth.AccessScope.CREATE_SHEETS,
    Smartsheet.Api.OAuth.AccessScope.READ_USERS,
    Smartsheet.Api.OAuth.AccessScope.ADMIN_USERS,
    Smartsheet.Api.OAuth.AccessScope.ADMIN_SHEETS,
    Smartsheet.Api.OAuth.AccessScope.ADMIN_WORKSPACES,
  },
  "key=Test"
);

// Take the user to the following URL
Debug.WriteLine(url);

// After the user accepts or declines the authorization they are taken to the redirect URL. The URL of the page
// the user is taken to can be used to generate an authorization RequestResult object.
string authorizationResponseURL = "http://localhost:3000/callback/?code=yn8kl1kvzzz31uj&expires_in=599997&state=key%3DTest";

// On this page pass in the full URL of the page to create an authorizationResult object  
AuthorizationResult authResult = oauth.ExtractAuthorizationResult(authorizationResponseURL);

// [todo]

# [todo]

auth_request_url = client.token.build_authorization_url(
  client_id: 'my-client-id',
  scopes: ['CREATE_SHEETS', 'WRITE_SHEETS'])

Successful Response:

// The user sees your app's consent page

GET https://app.smartsheet.com/b/authorize

POST https://app.smartsheet.com/b/authorize

Initiates the process to get authorization from the user. Smartsheet will redirect this URL to display your app's consent page with an explanation of the data the app will need access to. This consent page is autogenerated by Smartsheet based on a combination of the information you registered for your app and the parameters you send with the request.

Value	Description
client_id	Required. The client Id you obtained when you registered your app.
response_type	Required. Indicates whether the endpoint returns an authorization code. Must be set to "code".
scope	Required. Space-delimited list of access scopes to which you are asking the user to grant access. NOTE: No access scopes are necessary if you simply need to validate that the user has a Smartsheet account.
state	Optional. An arbitrary string of your choosing that is returned to your app; a successful roundtrip of this string helps ensure that your app initiated the request.

You can view code examples by clicking the corresponding tab in the dark-blue area in the rightmost pane. The cURL example shows a GET.

A correctly formatted Auth URL request looks like this: https://app.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE

At this point, the user can authorize your app to access their Smartsheet account, as in the following example:

After the user clicks "Allow" or "Deny", you'll receive a response from Smartsheet outlined in the next sections.

If the User Clicks Allow

Successful Response:

'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'

'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'

'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'

'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'

'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'

'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'

If the user clicks "Allow", Smartsheet redirects the user to the callback URL with the following parameters:

Value	Description
code	Authorization code required to obtain access token, such as 'sample6p9qisx6a'.
expires_in	Number of milliseconds code is valid once issued; this is currently 599135 milliseconds, or approx. 10 minutes--you must obtain an access token within that time.
state	The same value for state that you sent when you requested the authorization code.

At this point, you should verify the state value matches what you sent to the user when you requested the authorization code. This helps you determine that the response came from the user and not a malicious script. If the values do not match, you should reject the response.

For other error conditions, see the list of OAuth Error Types.

If the User Clicks Deny

If the user clicks "Deny", Smartsheet redirects the user to the callback URL with the following parameters:

Value	Description
error	"access_denied".
state	The same value for state that you sent when you requested the authorization code.

For other error conditions, see the list of OAuth Error Types.

Request an Access Token

Request an access token:

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

// Sample 2: Use plain text
curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&client_secret={app_secret}' \
-X POST

// Sample 1: Use a hash
// Create hash
var hash =
  crypto.createHash('sha256')
    .update('9samp7le3for71you' + '|' + 'sample6p9qisx6a')
        // ('Your App Secret' + '|' + 'Received Authorization Code')
    .digest('hex');

// Set options
var options = {
  queryParameters: {
    client_id: '1samp48lel5for68you',   // Your App Client ID
    code: 'sample6p9qisx6a',            // Received Authorization Code
    hash: hash
  },
  contentType: 'application/x-www-form-urlencoded'
};

// Get access token
smartsheet.tokens.getAccessToken(options)
  .then(function(token) {
  console.log(token);
})
.catch(function(error) {
    console.log(error);
  });

// Sample 2: Use plain text
// In progress

// Sample 1: Use a hash
// Get the token from the authorization result (see "Request an authorization code")
Token token = oauth.ObtainNewToken(
  authResult      // AuthorizationResult authResult
);

// Refresh an access token
Token tokenRefreshed = oauth.RefreshToken(token);

// Sample 2: Use plain text
// In progress

// [todo]

# [todo]

# Sample 1: Use a hash
hash = Digest::SHA256.hexdigest '9samp7le3for71you|sample6p9qisx6a'
                              # your_app_secret|your_code
smartsheet.token.get(
  client_id: '1samp48lel5for68you',
  code: 'sample6p9qisx6a',
  hash: hash
)

# Sample 2: Use plain text
# In progress

Successful Response:

{
    "token": {
        "access_token": "ll352u9jujauoqz4gstvsae05",
        "token_type": "bearer",
        "refresh_token": "e9x352a9mp4151le2505",
        "expires_in": 604799
    }
}

Error Response:

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

POST /token

Once you’ve successfully obtained an authorization code, the next step is to exchange the code for an access token. (Remember, the authorization code expires after 599135 milliseconds.)

Value	Description
client_id	Required. The client Id you obtained when you registered your app.
client_secret	Optional. Must use either this value or hash. Plain text method for sending this value. For example, client_secret={app_secret}. Encryption occurs at the HTTPS level.
code	Required. Authorization code returned in the previous step.
grant_type	Required. Must be set to "authorization_code".
hash	Optional. Must use either this value or client_secret. SHA-256 hash of your app secret concatenated with a pipe and the authorization code. For example, hash={SHA_256(app_secret|code)}.

If your request is successful, the response will contain a Token object. You can see an example of the Token object in the dark-blue area in the rightmost pane.

For possible error conditions, see the list of OAuth Error Types.

Refresh an Access Token

Refresh an access token:

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

Sample 2: Use plain text
curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=refresh_token&refresh_token={your_refresh_token}&client_id={your_client_id}&client_secret={app_secret}' \
-X POST

// Sample 1: Use a hash
// Create hash
var hash =
  crypto.createHash('sha256')
    .update('9samp7le3for71you' + '|' + 'sample6p9qisx6a')
        // ('Your App Secret' + '|' + 'Your App Refresh Token')
    .digest('hex');

// Set options
var options = {
  queryParameters: {
    client_id: '1samp48lel5for68you',   // Your App Client ID
    refresh_token: 'e9x352a9mp4151le2505',
    hash: hash
  },
  contentType: 'application/x-www-form-urlencoded'    
};

// Refresh access token
smartsheet.tokens.refreshAccessToken(options)
  .then(function(updatedToken) {
      console.log(updatedToken);
  })
  .catch(function(error) {
      console.log(error);
  });

// Sample 2: Use plain text
// In progress

// Sample 1: Use a hash
Token tokenRefreshed = oauth.RefreshToken(token);

// Sample 2: Use plain text
// In progress

// [todo]

# [todo]

# Sample 1: Use a hash
hash = Digest::SHA256.hexdigest '9samp7le3for71you|e9x352a9mp4151le2505'
                                # your_app_secret|refresh_token
smartsheet.token.refresh(
  client_id: '1samp48lel5for68you',
  refresh_token: 'e9x352a9mp4151le2505',
  hash: hash
)

# Sample 2: Use plain text
# In progress

Successful Response:

{
    "token": {
        "access_token": "new52u9jujauoqz4gstvsae05",
        "token_type": "bearer",
        "refresh_token": "new352a9mp4151le2505",
        "expires_in": 604799
    }
}

POST /token

Access tokens expire after 604799 seconds, which is approx 7 days. Use the refresh token to obtain a new access token and a new refresh token. Once you obtain the new tokens, you must use them in place of the old ones, which are no longer valid.

Value	Description
client_id	Required. Client Id for your app.
client_secret	Optional. Must use either this value or hash. Plain text method for sending this value. For example, client_secret={app_secret}. Encryption occurs at the HTTPS level.
grant_type	Required. Must be set to refresh_token.
hash	Optional. Must use either this value or client_secret. SHA-256 hash of your app secret concatenated with a pipe and the refresh token. For example, hash={SHA_256(app_secret|refresh_token)}.
refresh_token	Required. refresh_token value that came with the access token.
redirect_uri	Deprecated. If supplied, must match the redirect URI you registered for your app.

If your request is successful, the response will contain a Token object. You can see an example of the Token object in the dark-blue area in the rightmost pane.

OAuth Error Types

Value	Description
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 or the hash value does not match the app secret and/or code.
invalid_request	The request parameters are invalid or missing.
invalid_scope	One or more of the requested access scopes is invalid. Please check the list of access scopes.
unsupported_grant_type	grant_type must equal authorization_code or refresh_token.
unsupported_response_type	response_type must be set to code.

Work at Scale

Bulk Operations

The Smartsheet API supports a number of bulk operations that can operate on multiple objects. Unlike single-object operations, bulk operations allow you to create, update, or delete multiple objects in a single request. For example, if you want to update 10 rows within a sheet, do so using a single Update Rows request, rather than executing 10 separate requests - one for each row.

Optional Bulk Operations

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

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

Partial Success

In general, the default behavior for bulk operations is to fail outright if any of the objects in the request are invalid for some reason. If successful, Smartsheet creates/updates/deletes all objects in the request; if not, no objects are changed.

However, there are some operations that support partial success, which means the operation still succeeds even if one or more of the objects in the request fails for some reason (for example, an object is invalid). Here is another example: if you want to update more than one row, you send more than one row object in your request. If a row object is invalid, that row update will fail, but the other row updates will succeed. Partial success is not the default mode for an operation and you must explicitly enable it by using a query string parameter. This is noted in the documentation for operations that support partial success.

When partial success is enabled, and one or more of the objects in the request fail to be added/updated/deleted, a standard Result object is returned, but with a message of 'PARTIAL_SUCCESS' (instead of 'SUCCESS'), and a resultCode of 3. Additionally, the object contains a failedItems attribute -- an array of BulkItemFailure objects that contains an item for each object in the request that failed to be added/updated/deleted.

Paging

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

Paging Query String Parameters

Example request: list sheets with pagination query strings

curl https://api.smartsheet.com/2.0/sheets?include=attachments,source&includeAll=true \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  queryParameters: {
    include: "attachments",
    include: "source",
    includeAll: true
  }
};

// List sheets
smartsheet.sheets.listSheets(options)
    .then(function(response) {
        console.log(response);
    })
    .catch(function(error) {
        console.log(error);
    });

PaginatedResult<Sheet> sheets = smartsheet.SheetResources.ListSheets(
  new SheetInclusion[] { SheetInclusion.SOURCE },
  new PaginationParameters(
    true,           // includeAll
    null,           // int pageSize
    null)           // int page
);

// Specify pagination parameter 'includeAll'
PaginationParameters page_params = new PaginationParameters()
  .setIncludeAll(true);

// Specify `include` parameters
EnumSet include_params = EnumSet.of(SourceInclusion.SOURCE);

// List Sheets with pagination and include parameters
PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(include_params, page_params, null);

response = smartsheet_client.Sheets.list_sheets(include="attachments,source", include_all=True)
sheets = response.data

response = smartsheet.sheets.list(params: {include:"attachments,source", includeAll:true })
sheets = response

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

Value	Type	Description
includeAll	Boolean	If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified).
page	number	Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned.
pageSize	number	The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100.

Paged Responses

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

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

Rate Limiting

Handle "Rate limit exceeded" Error

To prevent abuse and undue stress on the Smartsheet servers, the API has a rate limiting feature (sometimes called throttling) that restricts users to 300 requests per minute per access token. Certain resource intensive operations, such as attaching a file and getting cell history, count as 10 requests. Smartsheet reserves 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 are rejected with an 429 HTTP status code, along with the following JSON response body:

{
    "errorCode": 4003,
    "message": "Rate limit exceeded."
}

Smartsheet recommends that you design your integration to gracefully handle this rate limit error. One way of doing that would be to have your integration sleep for 60 seconds when this error is encountered, and then subsequently retry the request. Alternatively, you might choose to implement exponential backoff (an error handling strategy whereby you periodically retry a failed request with progressively longer wait times between retries, until either the request succeeds or the certain number of retry attempts is reached).

Avoid Executing "Rapid Fire" Updates

If the only thing your integration does is execute an Update Rows request once every second for the same sheet, that would only amount to a total of 60 requests per minute -- well within rate limiting guidelines. However, updating the same object in such rapid succession could result in save errors that negatively impact both your integration as well as user experience within the Smartsheet app. To avoid this scenario, design your integration such that API requests are never executed with rapid-fire succession against the same Smartsheet object. For maximum efficiency, consider batching up changes and submitting them in a single request using a bulk operation (for example, Update Rows or Add Columns.

Execute Requests Serially

Executing multiple API requests in parallel to update a specific Smartsheet object results in reduced performance and often results in errors due to save collisions. To avoid this scenario, design your integration such that API requests to update a specific Smartsheet object are always executed serially (that is, execute one request at time, not beginning the next request until the previous request has completed).

API Reference

Attachments

Attachments can exist on a comment (that is, within a discussion), on a row, or on a sheet.

Objects

Attachment Object

Example: Attachment object

{
  "id": 4539352454850436,
  "name": "at3.pdf",
  "url": "https://www.example.com",
  "attachmentType": "FILE",
  "mimeType": "application/pdf",
  "urlExpiresInMillis": 120000,
  "sizeInKb": 56,
  "createdBy": {
    "name": "Jane Roe",
    "email": "jane.roe@company.com"
  },
  "createdAt": "2017-06-09T17:41:05Z"
}

id	number	Attachment Id
parentId	number	The Id of the parent
attachmentType	string	Attachment type (one of BOX_COM, DROPBOX*, EGNYTE*, EVERNOTE*, FILE, GOOGLE_DRIVE, LINK, or ONEDRIVE) *Not supported for all account types, see below.
attachmentSubType	string	Attachment sub type, valid only for the following: EGNYTE values: FOLDER GOOGLE_DRIVE values: DOCUMENT, DRAWING, PDF, PRESENTATION, or SPREADSHEET
mimeType	string	Attachment MIME type (PNG, etc.)
parentType	string	The type of object the attachment belongs to (one of COMMENT, ROW, or SHEET)
createdAt	timestamp	A timestamp of when the attachment was originally added
createdBy	User	User object containing name and email of the creator of this attachment
name	string	Attachment name
sizeInKb	number	The size of the file, if the attachmentType is FILE
url	string	Attachment temporary URL (files only)
urlExpiresInMillis	number	Attachment temporary URL time to live (files only)

Post an Attachment

Like the Smartsheet app, the Smartsheet API allows uploading files to sheets, rows, and comments. You can upload a file by performing either a simple upload or a multipart upload.

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

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

The max file size for uploads through the API is limited to 30mb.

Multipart Uploads

A multipart upload request must include the following HTTP headers:

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

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

Content-Disposition	Contains the following semicolon-delimited items: form-data name="partname" filename="filename" (only required for file parts) NOTE: Values specified in the Content-Disposition header must be URL-encoded.
Content-Type	The content type of the part: application/json for JSON objects, or the applicable MIME type for file parts

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

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

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

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

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

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

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

Simple Uploads

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

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

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

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

< Binary content for file >

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

Attach File to Comment

Example request: attach file to comment

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

// Enable FileStream
var fs = require("fs")

// Set options
var options = {
  sheetId: 1696803624483716,
  commentId: 7722333183016324,
  fileSize: 20765,
  fileName: "ProgressReport.docx",
  fileStream: fs.createReadStream("/Users/jdoe/Documents/ProgressReport.docx")
};

// Attach file to comment
smartsheet.sheets.addCommentFileAttachment(options)
  .then(function(attachment) {
      console.log(attachment);
  })
  .catch(function(error) {
      console.log(error);
  });

Attachment attachment = smartsheet.SheetResources.CommentResources.AttachmentResources.AttachFile(
  9283173393803140,           // sheetId
  1234567890234568,           // commentId
  filePath,
  "application/msword"
);

// Specify file to be attached
File file = new File("/Users/jdoe/Documents/ProgressReport.docx");

// Attach file to comment
Attachment attachment = smartsheet.sheetResources().commentResources().attachmentResources().attachFile(
  9283173393803140L,       // long sheetId
  1234567890234568L,       // long commentId
  file,
  "application/msword"
);

updated_attachment = smartsheet_client.Attachments.attach_file_to_comment(
  9283173393803140,       # sheet_id
  1234567890234568,       # comment_id
  ('ProgressReport.docx', 
    open('/path/to/ProgressReport.docx', 'rb'), 
    'application/msword')
)

# Sample 1: attach file from path
response = smartsheet.sheets.comments.attachments.attach_file_from_path(
  sheet_id: 4583173393803140,
  comment_id: 4293147074291588,
  path: '/Users/jdoe/Documents/ProgressReport.docx'
)
new_attachment = response[:result]

# Sample 2: attach file
filename = '/Users/jdoe/Documents/ProgressReport.docx'
file = File.open(filename)
file_length = File.size(filename)

response = smartsheet.sheets.comments.attachments.attach_file(
  sheet_id: 4583173393803140,
  comment_id: 4293147074291588,
  file: file,
  filename: filename,
  file_length: file_length
)
new_attachment = response[:result]

Example response

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

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

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

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

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

Attach File to Row

Example request: attach file to row

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

// Enable FileStream
var fs = require("fs")

// Set options
var options = {
  sheetId: 1696803624483716,
  rowId: 1049041355358596,
  fileSize: 20765,
  fileName: "ProgressReport.docx",
  fileStream: fs.createReadStream("/Users/jdoe/Documents/ProgressReport.docx")
};

// Attach file to row
smartsheet.sheets.addRowFileAttachment(options)
  .then(function(attachment) {
      console.log(attachment);
  })
  .catch(function(error) {
      console.log(error);
  });

Attachment attachment = smartsheet.SheetResources.RowResources.AttachmentResources.AttachFile(
  9283173393803140,           // sheetId
  0123456789012345,           // rowId
  filePath,
  "application/msword"
);

// Specify file to be attached
File file = new File("/Users/jdoe/Documents/ProgressReport.docx");

// Attach file to row
Attachment attachment = smartsheet.sheetResources().rowResources().attachmentResources().attachFile(
  9283173393803140L,       // long sheetId
  0123456789012345L,       // long rowId
  file,
  "application/msword"
);

updated_attachment = smartsheet_client.Attachments.attach_file_to_row(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  ('ProgressReport.docx', 
    open('/path/to/ProgressReport.docx', 'rb'), 
    'application/msword')
)

# Sample 1: Attach file from path
response = smartsheet.sheets.rows.attachments.attach_file_from_path(
  sheet_id: 4583173393803140,
  row_id: 4293147074291588,
  path: '/Users/jdoe/Documents/ProgressReport.docx'
)
new_attachment = response[:result]

# Sample 2: Attach file
filename = '/Users/jdoe/Documents/ProgressReport.docx'
file = File.open(filename)
file_length = File.size(filename)

response = smartsheet.sheets.rows.attachments.attach_file(
  sheet_id: 4583173393803140,
  row_id: 4293147074291588,
  file: file,
  filename: filename,
  file_length: file_length
)
new_attachment = response[:result]

Example response

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

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

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

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

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

Attach File to Sheet

Example request: attach file to sheet

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

// Enable FileStream
var fs = require("fs")

// Set options
var options = {
  sheetId: 1694401624483716,
  fileSize: 20765,
  fileName: "ProgressReport.docx",
  fileStream: fs.createReadStream("/Users/jdoe/Documents/ProgressReport.docx")
};

// Attach file to sheet
smartsheet.sheets.addFileAttachment(options)
  .then(function(attachment) {
      console.log(attachment);
  })
  .catch(function(error) {
      console.log(error);
  });

Attachment attachment = smartsheet.SheetResources.AttachmentResources.AttachFile(
  9283173393803140,           // sheetId
  filePath,
  "application/msword"
);

// Specify file to be attached
File file = new File("/Users/jdoe/Documents/ProgressReport.docx");

// Attach file to sheet
Attachment attachment = smartsheet.sheetResources().attachmentResources().attachFile(
  9283173393803140L,       // long sheetId
  file,
  "application/msword"
);

updated_attachment = smartsheet_client.Attachments.attach_file_to_sheet(
  9283173393803140,       # sheet_id
  ('ProgressReport.docx', 
    open('/path/to/ProgressReport.docx', 'rb'), 
    'application/msword')
)

# Sample 1: Attach file from path
response = smartsheet.sheets.attachments.attach_file_from_path(
  sheet_id: 4583173393803140,
  path: '/Users/jdoe/Documents/ProgressReport.docx'
)
new_attachment = response[:result]

# Sample 2: Attach file
filename = '/Users/jdoe/Documents/ProgressReport.docx'
file = File.open(filename)
file_length = File.size(filename)

response = smartsheet.sheets.attachments.attach_file(
  sheet_id: 4583173393803140,
  file: file,
  filename: filename,
  file_length: file_length
)
new_attachment = response[:result]

Example response

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

POST /sheets/{sheetId}/attachments

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

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

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

Attach URL to Comment

Example request: attach URL to comment

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

// Specify URL attachment
var attachment = {
  "name": "Search Engine",
  "attachmentType": "LINK",
  "url": "http://www.google.com"
};

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

// Attach URL to comment
smartsheet.sheets.addCommentAttachment(options)
  .then(function(updatedAttachment) {
    console.log(updatedAttachment);
  })
  .catch(function(error) {
    console.log(error);
  });

// Create attachment
Attachment attachmentSpecification = new Attachment
{
  Url = "http://www.google.com",
  AttachmentType = AttachmentType.LINK,
  Name = "Search Engine"
};

// Attach URL to comment
Attachment updatedAttachment = smartsheet.SheetResources.CommentResources.AttachmentResources.AttachUrl(
  9283173393803140,           // sheetId
  0123456789012345,           // commentId
  attachmentSpecification
);

// Create attachment
Attachment attachmentSpecification = new Attachment();
attachmentSpecification.setAttachmentType(AttachmentType.LINK)
  .setUrl("http://www.google.com")
  .setName("Search Engine");

// Attach URL to comment
Attachment updatedAttachment = smartsheet.sheetResources().commentResources().attachmentResources().attachUrl(
  9283173393803140L,       // long sheetId
  0123456789012345L,       // long commentId
  attachmentSpecification
);

# Create URL attachment
url_spec = smartsheet.models.Attachment({
  'name': 'Search Engine',
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

# Attach URL to comment
updated_attachment = smartsheet_client.Attachments.attach_url_to_comment(
  9283173393803140,       # sheet_id
  0123456789012345,       # comment_id
  url_spec)

# Specify options
body = {
  name: 'A URL',
  url: 'https://google.com',
  attachment_type: 'LINK'
}

# Attach URL to comment
response = smartsheet.sheets.comments.attachments.attach_url(
  sheet_id: 4583173393803140,
  comment_id: 4293147074291588,
  body: body
)
new_attachment = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "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"
  }
}

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

Attaches a URL to the comment.

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

The URL can be any of the following:

• Normal URL (attachmentType "LINK")
• Box.com URL (attachmentType "BOX_COM")
• Dropbox URL (attachmentType "DROPBOX")
• Egnyte URL (attachmentType "EGNYTE")
• Evernote URL (attachmentType "EVERNOTE")
• Google Drive URL (attachmentType "GOOGLE_DRIVE")
• OneDrive URL (attachmentType "ONEDRIVE")

Attach URL to Row

Example request: attach URL to row

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

// Specify URL attachment
var attachment = {
  "name": "Search Engine",
  "description": "A popular search engine",
  "attachmentType": "LINK",
  "url": "http://www.google.com"
};

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

// Attach URL to row
smartsheet.sheets.addRowAttachment(options)
  .then(function(updatedAttachment) {
    console.log(updatedAttachment);
  })
  .catch(function(error) {
    console.log(error);
  });

// Create attachment
Attachment attachmentSpecification = new Attachment
{
  Url = "http://www.google.com",
  AttachmentType = AttachmentType.LINK,
  Name = "Search Engine"
};

// Attach URL to row
Attachment updatedAttachment = smartsheet.SheetResources.RowResources.AttachmentResources.AttachUrl(
  9283173393803140,           // sheetId
  0123456789012345,           // rowId
  attachmentSpecification
);

// Create attachment
Attachment attachmentSpecification = new Attachment();
attachmentSpecification.setAttachmentType(AttachmentType.LINK)
  .setUrl("http://www.google.com")
  .setDescription("A popular search engine")
  .setName("Search Engine");

// Attach URL to row
Attachment updatedAttachment = smartsheet.sheetResources().rowResources().attachmentResources().attachUrl(
  9283173393803140L,       // long sheetId
  0123456789012345L,       // long rowId
  attachmentSpecification
);

# Create URL attachment
url_spec = smartsheet.models.Attachment({
  'name': 'Search Engine',
  'description': 'A popular search engine.'
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

# Attach URL to row
updated_attachment = smartsheet_client.Attachments.attach_url_to_row(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  url_spec)

# Specify options
body = {
  name: 'Search here',
  description: 'A search engine',
  url: 'https://google.com',
  attachment_type: 'LINK'
}

# Attach URL to row
response = smartsheet.sheets.rows.attachments.attach_url(
  sheet_id: 4583173393803140,
  row_id: 4293147074291588,
  body: body
)
new_attachment = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "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"
  }
}

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

Attaches a URL to the row.

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

The URL can be any of the following:

• Normal URL (attachmentType "LINK")
• Box.com URL (attachmentType "BOX_COM")
• Dropbox URL (attachmentType "DROPBOX")
• Egnyte URL (attachmentType "EGNYTE")
• Evernote URL (attachmentType "EVERNOTE")
• Google Drive URL (attachmentType "GOOGLE_DRIVE")
• OneDrive URL (attachmentType "ONEDRIVE")

Attach URL to Sheet

Example request: attach URL to sheet

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

// Specify URL attachment
var attachment = {
  "name": "Search Engine",
  "description": "A popular search engine",
  "attachmentType": "LINK",
  "url": "http://www.google.com"
};

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

// Attach URL to sheet
smartsheet.sheets.addAttachment(options)
  .then(function(updatedAttachment) {
      console.log(updatedAttachment);
  })
  .catch(function(error) {
      console.log(error);
  });

// Create attachment
Attachment attachmentSpecification = new Attachment
{
  Url = "http://www.google.com",
  AttachmentType = AttachmentType.LINK,
  Name = "Search Engine",
  Description = "A popular search engine"
};

// Attach URL to sheet
Attachment updatedAttachment = smartsheet.SheetResources.AttachmentResources.AttachUrl(
  9283173393803140,           // sheetId
  attachmentSpecification
);

// Create attachment
Attachment attachmentSpecification = new Attachment();
attachmentSpecification.setAttachmentType(AttachmentType.LINK)
  .setUrl("http://www.google.com")
  .setDescription("A popular search engine")
  .setName("Search Engine");

// Attach URL to sheet
Attachment updatedAttachment = smartsheet.sheetResources().attachmentResources().attachUrl(
  9283173393803140L,       // long sheetId
  attachmentSpecification
);

# Create URL attachment
url_spec = smartsheet.models.Attachment({
  'name': 'Search Engine',
  'description': 'A popular search engine.',
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

# Attach URL to sheet
updated_attachment = smartsheet_client.Attachments.attach_url_to_sheet(
  9283173393803140,       # sheet_id
  url_spec)

# Specify options
body = {
  name: 'Search Engine',
  description: 'A popular search engine.',
  url: 'http://www.google.com',
  attachment_type: 'LINK'
}

# Attach URL to sheet
response = smartsheet.sheets.attachments.attach_url(
  sheet_id: 4583173393803140,
  body: body
)
new_attachment = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "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"
  }
}

POST /sheets/{sheetId}/attachments

Attaches a URL to the sheet.

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

The URL can be any of the following:

• Normal URL (attachmentType "LINK")
• Box.com URL (attachmentType "BOX_COM")
• Dropbox URL (attachmentType "DROPBOX")
• Egnyte URL (attachmentType "EGNYTE")
• Evernote URL (attachmentType "EVERNOTE")
• Google Drive URL (attachmentType "GOOGLE_DRIVE")
• OneDrive URL (attachmentType "ONEDRIVE")

Delete Attachment

Example request: delete attachment

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

// Set options
var options = {
  sheetId: 2252168947361668,
  attachmentId: 7169782752536452,
};

// Delete attachment
smartsheet.sheets.deleteAttachment(options)
  .then(function(results) {
      console.log(results);
  })
  .catch(function(error) {
      console.log(error);
  });

smartsheet.SheetResources.AttachmentResources.DeleteAttachment(
  9283173393803140,           // sheetId
  7169782752536452            // attachmentId
);

smartsheet.sheetResources().attachmentResources().deleteAttachment(
  9283173393803140L,       // long sheetId
  7169782752536452L        // sheetAttachmentId
);

smartsheet_client.Attachments.delete_attachment(
  9283173393803140,       # sheet_id
  7169782752536452)       # attachment_id

smartsheet.sheets.attachments.delete(
  sheet_id: 4583173393803140,
  attachment_id: 7169782752536452
)

Example response

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

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

Deletes the attachment specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

Get Attachment

Example request: get attachment

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

// Set options
var options = {
  sheetId: 9283173393803140,
  attachmentId: 4583173393803140
};

// Get attachment
smartsheet.sheets.getAttachment(options)
  .then(function(attachment) {
      console.log(attachment);
  })
  .catch(function(error) {
      console.log(error);
  });

Attachment attachment = smartsheet.SheetResources.AttachmentResources.GetAttachment(
  9283173393803140,               // sheetId
  4583173393803140                // attachmentId
);

Attachment attachment = smartsheet.sheetResources().attachmentResources().getAttachment(
  9283173393803140L,       // long sheetId
  4583173393803140L        // long attachmentId
);

attachment = smartsheet_client.Attachments.get_attachment(
  9283173393803140,       # sheet_id
  4583173393803140)       # attachment_id

attachment = smartsheet.sheets.attachments.get(
  sheet_id: 9283173393803140,
  attachment_id: 4583173393803140
)

Example response

{
  "name": "expense_report_sample.png",
  "url": "https://api.smartsheet.com/download/aa402974cdb74cb58d9",
  "attachmentType": "FILE",
  "mimeType": "image/png",
  "id": 4583173393803140,
  "urlExpiresInMillis": 120000
}

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

Fetches a temporary URL that allows you to download an attachment. The urlExpiresInMillis attribute tells you how long the URL is valid.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Attachment object. For file attachments, this includes a temporary URL for downloading the file. Currently, the temporary URL is set to expire in 120000 milliseconds, or 2 minutes.
Access Scope	READ_SHEETS

List Attachments

Example request: list attachments

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

// Set options
var options = {
  sheetId: 9283173393803140
};

// List attachments
smartsheet.sheets.listAttachments(options)
  .then(function(attachmentsList) {
    console.log(attachmentsList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.AttachmentResources.ListAttachments(
  9283173393803140,           // sheetId
  null                        // PaginationParameters
);

// Omit pagination
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().listAttachments(
  9283173393803140L,               // long sheetId
  null                             // PaginationParameters
);

# Sample 1: List All
response = smartsheet_client.Attachments.list_all_attachments(
  9283173393803140,       # sheet_id
  include_all=True)
attachments = response.data

# Sample 2: Paginate the list of attachments
response = smartsheet_client.Attachments.list_all_attachments(
  9283173393803140,       # sheet_id
  page_size=10, 
  page=1)
pages = response.total_pages
attachments = response.data

response = smartsheet.sheets.attachments.list(
  sheet_id: 9283173393803140
)
attachments = response[:data]

Example response

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

GET /sheets/{sheetId}/attachments

Gets a list of all attachments that are on the sheet, including sheet, row, and discussion-level attachments.

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

List Discussion Attachments

Example request: list discussion attachments

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

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

// List discussion attachments
smartsheet.sheets.listDiscussionAttachments(options)
  .then(function(attachmentsList) {
      console.log(attachmentsList);
  })
  .catch(function(error) {
      console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.DiscussionResources.AttachmentResources.ListAttachments(
  9283173393803140,               // sheetId
  1234567890123456,               // discussionId
  null                            // PaginationParameters
);

// Omit pagination
PagedResult<Attachment> attachments = smartsheet.sheetResources().discussionResources().attachmentResources().getAttachments(
  9283173393803140L,       // long sheetId
  1234567890123456L,       // long discussionId
  null                     // PaginationParameters
);

# Sample 1: List All
response = smartsheet_client.Attachments.list_discussion_attachments(
  9283173393803140,       # sheet_id 
  1234567890123456,       # discussion_id 
  include_all=True)
attachments = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Attachments.list_discussion_attachments(
  9283173393803140,       # sheet_id
  1234567890123456,       # discussion_id 
  page_size=10, 
  page=1)
pages = response.total_pages
attachments = response.data

response = smartsheet.sheets.discussions.attachments.list(
  sheet_id: 9283173393803140,
  discussion_id: 1234567890123456
)
attachments = response[:data]

Example response

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

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

Gets a list of all attachments that are in the discussion.

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

List Row Attachments

Example request: list row attachments

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

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

// List row attachments
smartsheet.sheets.getRowAttachments(options)
  .then(function(attachmentsList) {
      console.log(attachmentsList);
  })
  .catch(function(error) {
      console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.RowResources.AttachmentResources.ListAttachments(
  2252168947361668,               // sheetId
  4293147074291588,               // rowId
  null                            // PaginationParameters
);

// Omit pagination
PagedResult<Attachment> attachments = smartsheet.sheetResources().rowResources().attachmentResources().getAttachments(
  2252168947361668L,       // long sheetId
  4293147074291588L,       // long rowId
  null                     // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Attachments.list_row_attachments(
  2252168947361668,       # sheet_id 
  4293147074291588,       # row_id 
  include_all=True)
attachments = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Attachments.list_row_attachments(
  2252168947361668,       # sheet_id 
  4293147074291588,       # row_id 
  page_size=10, 
  page=1)
pages = response.total_pages
attachments = response.data

response = smartsheet.sheets.rows.attachments.list(
  sheet_id: 2252168947361668,
  row_id: 4293147074291588
)
attachments = response[:data]

Example response

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

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

Gets a list of all attachments that are on the row, including row and discussion-level attachments.

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

Versioning

Attach New Version

Example request: attach new version

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

// Enable FileStream
var fs = require("fs")

// Set options
var options = {
  sheetId: 9283173393803140,
  attachmentId: 0123456789123456,
  fileSize: 17291,
  fileName: "ProgressReport.docx",
  fileStream: fs.createReadStream("/Users/jdoe/Documents/ProgressReport.docx")
};

// Attach new version
smartsheet.sheets.attachNewVersion(options)
  .then(function(updatedAttachment) {
    console.log(updatedAttachment);
  })
  .catch(function(error) {
    console.log(error);
  });

Attachment attachment = smartsheet.SheetResources.AttachmentResources.VersioningResources.AttachNewVersion(
  9283173393803140,               // sheetId
  0123456789123456,               // attachmentId
  filePath,
  "application/msword"
);

// Specify the new file to be attached
File file = new File("/Users/jdoe/Documents/ProgressReport.docx");

// Attach new version of the file
Attachment attachment = smartsheet.sheetResources().attachmentResources().versioningResources().attachNewVersion(
  9283173393803140L,       // long sheetId
  0123456789123456L,       // long attachmentId
  file,
  "application/msword"
);

response = smartsheet_client.Attachments.attach_new_version(
  9283173393803140,       # sheet_id
  0123456789123456,       # attachment_id
  ('ProgressReport.docx',
    open('/path/to/ProgressReport.docx', 'rb'),
    'application/msword')
)

updated_attachment = response.result

# Sample 1: Attach new version from path
response = smartsheet.sheets.attachments.attach_new_version_from_path(
  sheet_id: 9283173393803140,
  attachment_id: 0123456789123456,
  path: '/Users/jdoe/Documents/ProgressReport.docx'
)
updated_attachment = response[:result]

# Sample 2: Attach new version
filename = '/Users/jdoe/Documents/ProgressReport.docx'
file = File.open(filename)
file_length = File.size(filename)

response = smartsheet.sheets.attachments.attach_new_version(
  sheet_id: 9283173393803140,
  attachment_id: 0123456789123456,
  file: file,
  filename: filename,
  file_length: file_length
)
updated_attachment = response[:result]

Example response

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

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

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

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

Delete All Versions

Example request: delete all versions

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

// Set options
var options = {
  sheetId: 2252168947361668,
  attachmentId: 5510069950408580
};

// Delete all versions of the attachment
smartsheet.sheets.deleteAllAttachmentVersions(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.SheetResources.AttachmentResources.VersioningResources.DeleteAllVersions(
  9283173393803140,               // sheetId
  0123456789123456                // attachmentId
);

smartsheet.sheetResources().attachmentResources().versioningResources().deleteAllVersions(
  9283173393803140L,       // long sheetId
  0123456789123456L        // long attachmentId
);

smartsheet_client.Attachments.delete_attachment_versions(
  9283173393803140,       # sheet_id
  0123456789123456)       # attachment_id

smartsheet.sheets.attachments.delete_all_versions(
  sheet_id: 9283173393803140,
  attachment_id: 0123456789123456
)

Example response

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

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

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

List Versions

Example request: list versions

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

// Set options
var options = {
  sheetId: 2252168947361668,
  attachmentId: 5510069950408580
};

// List versions of the attachment
smartsheet.sheets.listAttachmentVersions(options)
  .then(function(versionList) {
    console.log(versionList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.AttachmentResources.VersioningResources.ListVersions(
  2252168947361668,               // sheetId
  5510069950408580,               // attachmentId
  null                            // PaginationParameters
);

// Omit pagination
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().versioningResources().listAllVersions(
  2252168947361668L,       // long sheetId
  5510069950408580L,       // long attachmentId
  null                     // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Attachments.list_attachment_versions(
  2252168947361668,       # sheet_id 
  5510069950408580,       # attachment_id
  include_all=True)
versions = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Attachments.list_attachment_versions(
  2252168947361668,       # sheet_id  
  5510069950408580,       # attachment_id 
  page_size=5, 
  page=1)
pages = response.total_pages
versions = response.data

response = smartsheet.sheets.attachments.list_versions(
  sheet_id: 4583173393803140,
  attachment_id: 5510069950408580
)
versions = response[:data]

Example response

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

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

Gets a list of all versions of the given attachmentId in order from newest to oldest.

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

Automation Rules

Automation is a catch-all term for approvals, notifications, and update requests. You can delete, update, or retrieve various automation settings through the API. You cannot create new automation rules programmatically.

Objects

AutomationRule Object

Example: AutomationRule object

{
  "id": 789994550205316,
  "name": "Approval Request",
  "enabled": true,
  "createdBy": {
    "email": "john.doe@smartsheet.com"
  },
  "createdAt": "2017-12-14T18:31:55Z",
  "modifiedBy": {
    "email": "john.doe@smartsheet.com"
  },
  "modifiedAt": "2017-12-14T18:31:55Z",
  "userCanModify": true,
  "action": {
    "type": "APPROVAL_REQUEST_ACTION",
    "recipients": [
      {
        "email": "jane.roe@smartsheet.com"
      }
    ],
    "frequency": "IMMEDIATELY",
    "includeAllColumns": true,
    "includeAttachments": true,
    "includeDiscussions": true,
    "notifyAllSharedUsers": false
  }
}

id	number	AutomationRule Id
action	AutomationAction	AutomationAction object containing information for this rule, such as type, recipients, and frequency.
createdAt	timestamp	A timestamp of when the rule was originally added.
createdBy	User	User object containing name and email of the creator of this rule.
disabledReason	string	Machine-readable reason a rule is disabled. See table of Disabled Reasons.
disabledReasonText	string	Descriptive reason a rule is disabled.
enabled	Boolean	If true, indicates that the rule is active.
modifiedAt	timestamp	The datetime for when the change was made to the rule.
modifiedBy	User	User object containing the name and email of the user that made the change.
name	string	Rule name as shown in the UI.
userCanModify	Boolean	If true, indicates that the current user can modify the rule.

AutomationAction Object

Example: AutomationAction object

{
  "type": "APPROVAL_REQUEST_ACTION",
  "recipients": [
    {
      "email": "jane.roe@smartsheet.com"
    }
  ],
  "frequency": "IMMEDIATELY",
  "includeAllColumns": true,
  "includeAttachments": true,
  "includeDiscussions": true,
  "notifyAllSharedUsers": false
}

includedColumnIds	long[]	Specifies which columns to include in message.
recipientColumnIds	long[]	Array of column Ids from which to collect email recipients.
type	string	One of three types: APPROVAL_REQUEST_ACTION, NOTIFICATION_ACTION, or UPDATE_REQUEST_ACTION.
frequency	string	Must be one of the following values: DAILY, HOURLY, IMMEDIATELY, or WEEKLY. Ignored for date-based rules.
includeAllColumns	Boolean	If true (default), all columns are included in email contents.
includeAttachments	Boolean	If true, includes attachments.
includeDiscussions	Boolean	If true, includes discussions.
message	string	Email body.
notifyAllSharedUsers	Boolean	If true, notifications are sent to all users shared to the sheet.
recipients	Recipient	Array of Recipient objects that contains one or more Email objects.
subject	string	Email subject line.

Delete an Automation Rule

Example request: delete an automation rule

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

// Set options
var options = {
  sheetId: 9283173393803140,
  automationRuleId: 789004550205316
};

// Delete automation rule
smartsheet.sheets.deleteAutomationRule(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

AutomationRule automationRule = smartsheet.SheetResources.AutomationRuleResources.DeleteAutomationRule(
  9283173393803140,               // sheetId
  789004550205316                 // automationRuleId
);

// Not yet implemented

# Not yet implemented

smartsheet.sheets.automation_rules.delete(
  sheet_id: 9283173393803140,
  automation_rule_id: 789004550205316
)

Example response

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

DELETE /sheets/{sheetId}/automationrules/{automationRuleId}

Deletes an automation rule.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

Get an Automation Rule

Example request: get an automation rule

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

// Set options
var options = {
  sheetId: 9283173393803140,
  automationRuleId: 789994550205316
};

// Get automation rule
smartsheet.sheets.getAutomationRule(options)
  .then(function(automationRule) {
    console.log(automationRule);
  })
  .catch(function(error) {
    console.log(error);
  });

AutomationRule automationRule = smartsheet.SheetResources.GetAutomationRule(
  9283173393803140,              // sheetId
  789994550205316                // automationRuleId
);

// Not yet implemented

# Not yet implemented

rule = smartsheet.sheets.automation_rules.get(
  sheet_id: 9283173393803140,
  automation_rule_id: 789994550205316
)

Example response

{
  "id": 789994550205316,
  "name": "Approval Request",
  "enabled": true,
  "createdBy": {
    "email": "john.doe@smartsheet.com"
  },
  "createdAt": "2017-12-14T18:31:55Z",
  "modifiedBy": {
    "email": "john.doe@smartsheet.com"
  },
  "modifiedAt": "2017-12-14T18:31:55Z",
  "userCanModify": true,
  "action": {
    "type": "APPROVAL_REQUEST_ACTION",
    "recipients": [
      {
        "email": "jane.roe@smartsheet.com"
      }
    ],
    "frequency": "IMMEDIATELY",
    "includeAllColumns": true,
    "includeAttachments": true,
    "includeDiscussions": true,
    "notifyAllSharedUsers": false
  }
}

GET /sheets/{sheetId}/automationrules/{automationRuleId}

Returns the specified automation rule, including any action values.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	AutomationRule object.
Access Scope	READ_SHEETS

List All Automation Rules

Example request: list all automation rules

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

// Set options
var options = {
  sheetId: 9283173393803140
};

// List automation rules
smartsheet.sheets.listAutomationRules(options)
  .then(function(automationRulesList) {
    console.log(automationRulesList);
  })
  .catch(function(error) {
    console.log(error);
  });

PaginatedResult<AutomationRule> AutomationRules = smartsheet.SheetResources.AutomationRuleResources.ListAutomationRules(
  9283173393803140,  // sheetId
  null               // PaginationParameters
);

// Not yet implemented

# Not yet implemented

response = smartsheet.sheets.automation_rules.list(
  sheet_id: 9283173393803140
)
rules = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
  "data": [
    {
      "id": 789994550205316,
      "name": "Approval Request",
      "enabled": true,
      "createdBy": {
        "email": "john.doe@smartsheet.com"
      },
      "createdAt": "2017-12-14T18:31:55Z",
      "modifiedBy": {
        "email": "john.doe@smartsheet.com"
      },
      "modifiedAt": "2017-12-14T18:31:55Z",
      "userCanModify": true,
      "action": {
        "type": "APPROVAL_REQUEST_ACTION",
        "recipients": [
          {
            "email": "jane.roe@smartsheet.com"
          }
        ],
        "frequency": "IMMEDIATELY",
        "includeAllColumns": true,
        "includeAttachments": true,
        "includeDiscussions": true,
        "notifyAllSharedUsers": false
      }
    },
    {
      "id": 3377755522834820,
      "name": "Notification",
      "enabled": true,
      "createdBy": {
        "email": "john.doe@smartsheet.com"
      },
      "createdAt": "2017-12-14T18:31:37Z",
      "modifiedBy": {
        "email": "john.doe@smartsheet.com"
      },
      "modifiedAt": "2017-12-14T18:31:37Z",
      "userCanModify": true,
      "action": {
        "type": "NOTIFICATION_ACTION",
        "recipients": [
          {
            "email": "jane.roe@smartsheet.com"
          }
        ],
        "frequency": "DAILY",
        "includeAllColumns": true,
        "includeAttachments": true,
        "includeDiscussions": true,
        "notifyAllSharedUsers": false
      }
    }
  ]
}

GET /sheets/{sheetId}/automationrules

Returns all automation rules associated with the specified sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	IndexResult object containing an array of AutomationRule objects.
Access Scope	READ_SHEETS

Update an Automation Rule

Example request: update an automation rule

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X PUT \
-d '{
    "action": {
        "type": "APPROVAL_REQUEST_ACTION",
        "recipients": [{
            "email": "jane.roe@smartsheet.com"
        }],
        "frequency": "WEEKLY"
    }
}'

// Specify the changes
var body = {
  "name": "Approval Request",
  "action": {
    "type": "APPROVAL_REQUEST_ACTION",
    "recipients": [
      {
        "email": "jane.roe@smartsheet.com"
      }
    ],
    "frequency": "WEEKLY",
    "includeAllColumns": true,
    "includeAttachments": true,
    "includeDiscussions": true,
    "notifyAllSharedUsers": false
  }
};

// Set options
var options = {
  sheetId: 4583173393803140,
  automationRuleId: 789994550205316,
  body: body
  };

// Update the automation rule
smartsheet.sheets.updateAutomationRule(options)
  .then(function(updatedAutomationRule) {
    console.log(updatedAutomationRule);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set recipient
Recipient recipient = new Recipient
{
  Email = "jane.roe@smartsheet.com"
};

// Specify the changes
AutomationRule autoRule = new AutomationRule
{
  Id = 789994550205316,
  Action = new AutomationAction
  {
    Recipients = new[] { recipient },
    Type = AutomationActionType.NOTIFICATION_ACTION,
    Frequency = AutomationActionFrequency.WEEKLY
  }
};

// Update the automation rule
AutomationRule automationRule = smartsheet.SheetResources.UpdateAutomationRule(
  4583173393803140,  // sheetId
  autoRule
);

// Not yet implemented

# Not yet implemented

smartsheet.sheets.automation_rules.update(
  sheet_id: 4583173393803140,
  automation_rule_id: 789994550205316,
  body: {
    name: 'Approval Request',
    enabled: true,
    action: {
      type: 'APPROVAL_REQUEST_ACTION',
      recipients: [
        {
            email: 'jane.roe@smartsheet.com'
        }
      ],
      frequency: 'WEEKLY',
      include_all_columns: true,
      include_attachments: true,
      include_discussions: true,
      notify_all_shared_users: false
    }
})

Example response

{
  "id": 789994550205316,
  "name": "Approval Request",
  "enabled": true,
  "createdBy": {
    "email": "john.doe@smartsheet.com"
  },
  "createdAt": "2017-12-14T18:31:55Z",
  "modifiedBy": {
    "email": "john.doe@smartsheet.com"
  },
  "modifiedAt": "2017-12-14T18:47:36Z",
  "userCanModify": true,
  "action": {
    "type": "APPROVAL_REQUEST_ACTION",
    "recipients": [
      {
        "email": "jane.roe@smartsheet.com"
      }
    ],
    "frequency": "WEEKLY",
    "includeAllColumns": true,
    "includeAttachments": true,
    "includeDiscussions": true,
    "notifyAllSharedUsers": false
  }
}

PUT /sheets/{sheetId}/automationrules/{automationRuleId}

Updates an existing automation rule.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	An AutomationRule object. When sending an AutomationRule, you must always specify action.type and it must match the existing rule type.
Returns	Result object containing the updated AutomationRule object
Access Scope	WRITE_SHEETS

Related Items

Disabled Reasons for Automation Rules

APPROVAL_COLUMN_MISSING	This rule's approval status column has been deleted.
APPROVAL_COLUMN_WRONG_TYPE	The approval column must be a dropdown column.
AUTOMATION_NOT_ENABLED_FOR_ORG	To create or edit automated actions, you need to upgrade your organization account to a Business or Enterprise plan.
COLUMN_MISSING	A column referenced by this rule has been deleted.
COLUMN_TYPE_INCOMPATIBLE	A column referenced by this rule has been changed to an incompatible column type.
NO_POTENTIAL_RECIPIENTS	This rule has no recipients that will be able to receive notifications based on this sheet's permission settings or this account's approved domain sharing list.
NO_VALID_SELECTED_COLUMNS	All selected columns for this rule have been deleted.

Cells

A collection of cells comprises each row in a sheet.

Objects

Cell Object

Example: Cell object

{
  "columnType": "TEXT_NUMBER",
  "value": "Revision 1",
  "displayValue": "Revision 1",
  "columnId": 4583173393803140
}

columnId	number	The Id of the column that the cell is located in
columnType	string	See type definition on the Column object. Only returned if the include query string parameter contains columnType.
conditionalFormat	string	The format descriptor describing this cell's conditional format (see Formatting). Only returned if the include query string parameter contains format and this cell has a conditional format applied.
displayValue	string	Visual representation of cell contents, as presented to the user in the UI. See Cell Reference.
format	string	The format descriptor (see Formatting) Only returned if the include query string parameter contains format and this cell has a non-default format applied.
formula	string	The formula for a cell, if set, for instance =COUNTM([Assigned To]3). NOTE: calculation errors or problems with a formula do not cause the API call to return an error code. Instead, the response contains the same value as in the UI, such as cell.value = "#CIRCULAR REFERENCE".
hyperlink	Hyperlink	A hyperlink to a URL, sheet, or report
image	Image	The image that the cell contains. Only returned if the cell contains an image.
linkInFromCell	CellLink	An inbound link from a cell in another sheet. This cell's value mirrors the linked cell's value.
linksOutToCells	CellLink[]	An array of CellLink objects. Zero or more outbound links from this cell to cells in other sheets whose values mirror this cell's value.
objectValue	ObjectValue	Optionally included object representation of the cell's value. Used for updating predecessor cell values or for multi-contact details.
overrideValidation	Boolean	(Admin only) Indicates whether the cell value can contain a value outside of the validation limits (value = true). When using this parameter, you must also set strict to false to bypass value type checking. This property is honored for POST or PUT actions that update rows.
strict	Boolean	Set to false to enable lenient parsing. Defaults to true. You can specify this attribute in a request, but it is never present in a response. See Cell Value Parsing for more information about using this attribute.
value	string, number, or Boolean	A string, a number, or a Boolean value -- depending on the cell type and the data in the cell. Cell values larger than 4000 characters are silently truncated. An empty cell returns no value. See Cell Reference.

Cell History Object

Extends the Cell object.

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

CellLink Object

Represents a link to a cell in a different sheet.

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

Duration Object

Extends the ObjectValue object.

In a project sheet, represents a value in a duration cell, or a lag value of a predecessor.

objectType	string	DURATION
days	number	The number of days for this duration.
elapsed	Boolean	If true, indicates this duration represents elapsed time, which ignores non-working time.
hours	number	The number of hours for this duration.
milliseconds	number	The number of milliseconds for this duration.
minutes	number	The number of minutes for this duration.
negative	Boolean	When used as a predecessor's lag value, indicates whether the lag is negative (if true), or positive (false). The individual duration values themselves (for example, days, hours, or minutes) is always positive.
seconds	number	The number of seconds for this duration.
weeks	number	The number of weeks for this duration.

Hyperlink Object

Represents a hyperlink to a dashboard, report, sheet, or URL.

reportId	number	If non-null, this hyperlink is a link to the report with this Id.
sheetId	number	If non-null, this hyperlink is a link to the sheet with this Id.
sightId	number	If non-null, this hyperlink is a link to the dashboard with this Id.
url	string	When the hyperlink is a URL link, this property contains the URL value. When the hyperlink is a dashboard/report/sheet link (that is, sightId, reportId, or sheetId is non-null), this property contains the permalink to the dashboard, report, or sheet.

ObjectValue Object

Example: ObjectValue object

{
    "cells": [{
        "columnId": 285878125913988,
        "objectValue": {
            "objectType": "MULTI_PICKLIST",
            "values": ["hello", "world"]
        }

    }]
}

The base object for values found in the Cell.objectValue attribute. Its objectType attribute indicates the type of the object. This object itself is not used directly.

objectType	string	One of ABSTRACT_DATETIME, CONTACT, DATE, DATETIME, DURATION, MULTI_CONTACT, MULTI_PICKLIST, or PREDECESSOR_LIST

Predecessor Object

rowId	number	The Id of the predecessor row
type	string	The type of the predecessor. One of FF, FS, SF, or SS.
inCriticalPath	Boolean	True if this predecessor is in the critical path. Read-only.
invalid	Boolean	True if the row referenced by rowId is not a valid row in this sheet, or there is a circular reference (displayed in the Smartsheet app as "#REF"). Read-only. Omitted if false.
lag	Duration	The lag value of this predecessor. Omitted if there is no lag.
rowNumber	number	The row number of the predecessor row. Omitted if invalid is true. Read-only.

PredecessorList Object

Example request: update row for a predecessor cell

curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows?include=objectValue' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '[{"id": "6572427401553796", "cells": [{"columnId": 7518312134403972,"objectValue": {"objectType": "PREDECESSOR_LIST","predecessors": [{"rowId": 567735454328708,"type": "FS","lag": {"objectType": "DURATION","days": 2,"hours": 4}}]}}]}]'

// Not yet implemented

// Not yet implemented

// Not yet implemented

# Not yet implemented

# Not yet implemented

Example response

{
  "message": "SUCCESS",
  "result": [{
    "id": 6572427401553796,
    "rowNumber": 2,
    "expanded": true,
    "createdAt": "2015-01-09T11:41:55-08:00",
    "modifiedAt": "2015-02-23T15:36:07-08:00",
    "cells": [{
      "columnId": 7518312134403972,
      "value": "1FS +2d 4h",
      "objectValue": {
        "objectType": "PREDECESSOR_LIST",
        "predecessors": [{
          "rowId": 567735454328708,
          "rowNumber": 1,
          "type": "FS",
          "lag": {
            "objectType": "DURATION",
            "days": 2,
            "hours": 4
          }
        }]
      },
      "displayValue": "1FS +2d 4h"
    }]
  }]
}

Extends the ObjectValue object.

In a project sheet with dependencies enabled, the objectValue attribute for predecessor cells is an object of this type, which represents the predecessors for the row.

objectType	string	PREDECESSOR_LIST
predecessors	Predecessor[]	Array of Predecessor objects.

Get Cell History

Example request: get cell history

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

// Set options
var options = {
  sheetId: 9283173393803140,
  rowId: 0123456789012345,
  columnId: 4567890123456789
};

// Get cell history
smartsheet.sheets.getCellHistory(options)
  .then(function(history) {
      console.log(history);
  })
  .catch(function(error) {
      console.log(error);
  });

// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<CellHistory> results = smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(
  9283173393803140,               // sheetId
  0123456789012345,               // rowId
  4567890123456789,               // columnId
  null,                           // IEnumerable<CellInclusion> includes
  null                            // PaginationParameters
);

// Sample 2: Specify 'include' parameter with value of "COLUMN_TYPE" and 'includeAll' parameter with value of 'true'
PaginatedResult<CellHistory> results = smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(
  9283173393803140,               // sheetId
  0123456789012345,               // rowId
  4567890123456789,               // columnId
  new CellInclusion[] { CellInclusion.COLUMN_TYPE },
  new PaginationParameters(
    true,                       // Boolean includeAll
    null,                       // int pageSize
    null)                       // int page
);

// Omit pagination
PagedResult<CellHistory> cellHistory = smartsheet.sheetResources().rowResources().cellResources().getCellHistory(
  9283173393803140L,       // long sheetId
  0123456789012345L,       // long rowId
  4567890123456789L,       // long columnId
  null                     // PaginationParameters
);

# Sample 1: Get history
response = smartsheet_client.Cells.get_cell_history(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  4567890123456789,       # column_id
  include_all=True)
revisions = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Cells.get_cell_history(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  4567890123456789,       # column_id
  page_size=5,
  page=1)
pages = response.total_pages
revisions = response.data

response = smartsheet.sheets.cells.get_history(
  sheet_id: 9283173393803140,
  row_id: 0123456789012345,
  column_id: 4567890123456789
)
revisions = response[:data]

Example response

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

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

Gets the cell modification history.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- comma-separated list of elements to copy: columnType -- includes the columnType attribute for each Cell object objectValue -- when used in combination with a level query parameter, includes the email addresses for a multi-contact cell.
	level (optional): specifies whether multi-contact data is returned in a backwards-compatible, text format (level=0, default) or as multi-contact data (level=1).
	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Cell History objects. For more details, see Cell Reference.
Access Scope	READ_SHEETS

Update Cells

To update the cells in a sheet, use the Update Rows operation.

Related Items

Cell Links

Creating or updating cell links via the cell.linkInFromCell attribute is a special operation. A given row or cell update operation may contain only link updates, or no link updates. Attempting to mix row/cell updates with cell link updates results in error code 1115. Additionally, a CellLink object can only be added to an existing cell, so the cell.linkInFromCell attribute is not allowed when POSTing a new row to a sheet.

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

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

Cell Reference

Cell Value Representation

Cell objects retrieved through the Smartsheet APIs have two main attributes representing cell values: Cell.value, and Cell.displayValue. A third attribute, Cell.objectValue is currently used only for adding and updating predecessors, or for multi-contact or multi-picklist details, such as email addresses or values in a multi-picklist. An empty cell returns no value.

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

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

Column Type	Possible Types for Cell.value	Returns Cell.displayValue?
ABSTRACT_DATETIME	string: a project date and time in ISO-8601 format, or a free-form text value. number: see Dates and Times for how to request dates to be returned as numbers.	No.
CHECKBOX	Boolean: true if the checkbox is checked, false if unchecked, no value if the cell hasn't been touched yet. string: a free-form text value.	No.
CONTACT_LIST	string: an email address representing a contact, or a free-form text value.	Yes: same as value for free-form strings; for contacts, the contact's name if any, else their email address.
DATE	string: a date in ISO-8601 format, or a free-form text value. number: see Dates and Times for how to request dates to be returned as numbers.	No.
DURATION	string: a duration value such as "4d 6h 30m" in the user's locale, or a free-form text value. See the Help Center for more information on durations.	Yes: same as value
MULTI_CONTACT_LIST	string: only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying, otherwise the column type is TEXT_NUMBER.	Yes: same as value; to see actual email addresses, see below.
MULTI_PICKLIST	string: only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying, otherwise the column type is TEXT_NUMBER.	Yes: same as value; to see objectValue, see below.
PICKLIST	string: one of the picklist's column options, or a free-form text value. number: numeric values	Yes: same as value for strings; for number values, the number with formatting applied.
PREDECESSOR	string: a comma-delimited predecessor list such as "12FS +3d 4h, 14SS", or a free-form text value. See the Help Center for more information on predecessors.	Yes: same as value
TEXT_NUMBER	string: free-form text values number: numeric values	Yes: same as value for strings; for number values, the number with formatting applied.

Cell.objectValue is an object representation of a cell's value and is currently used for adding or updating predecessor cell values, or for multi-contact details, such as email addresses.

• For predecessors, it provides a more "programmer friendly" format for assembling predecessors. To update a cell's predecessors, set objectValue to a PredecessorList object containing Predecessor objects.
• For multi-contact or multi-picklist details, use both a level query parameter and an include=objectValue query to see email addresses rather than display names or to see multi-picklist values.

Cell Value Parsing

The flexibility in cell value data types is a powerful feature in the Smartsheet application; however, it poses a challenge for an API in terms of parsing. Being too flexible might 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 string value? Probably not.

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

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

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

ABSTRACT_DATETIME

lenient	Smartsheet attempts 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, Smartsheet recognizes the date and stores it as such. All other values are simply text values.
strict	The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of numericDates set to true to have Smartsheet convert epoch time to human readable dates. See Dates and Times for more information.

CHECKBOX

lenient	Boolean values and string values of true and false are handled the same as strict. All other values are saved as text values.
strict	Only Boolean values (true or false) are valid.

CONTACT_LIST

lenient	If the value is a valid email address, Smartsheet handles it the same as strict. If not, Smartsheet saves the value as a text value.
strict	The value must be a valid email address. If displayValue is set, Smartsheet uses that as the name; otherwise, if Smartsheet finds a match among the the access token owner's contacts, Smartsheet associates this cell with that existing contact.

DATE

lenient	Smartsheet attempts 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, Smartsheet recognizes the date and stores it as such. All other values are simply text values.
strict	The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of numericDates set to true to have Smartsheet convert epoch time to human readable dates. See Dates and Times for more information.

DURATION

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

MULTI_CONTACT_LIST

N/A	Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

MULTI_PICKLIST

N/A	Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

PICKLIST

lenient	All numeric and text values are valid. Formatted numbers are parsed like TEXT_NUMBER formatted numbers.
strict	The value must be a string and must be one of the options for the picklist.

PREDECESSOR

N/A	Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

TEXT_NUMBER

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") are parsed to their numeric equivalents, based on the locale of the access token owner, with the proper formatting enabled for the cell.
strict	All numeric and text values are valid and are interpreted literally.

Contact List Columns

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

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

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

Hyperlinks

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

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

Images in Cells

For details about working with images in cells, see Cell Images.

Cell Images

A cell image is an image that has been uploaded to a cell within a sheet.

Objects

Image Object

id	string	Image Id
altText	string	Alternate text for the image
height	number	Original height (in pixels) of the uploaded image
width	number	Original width (in pixels) of the uploaded image

ImageUrl Object

Example: ImageUrl object

{
  "imageId": "e1znCxhuZo_soEJtUmmX_A",
  "url": "https://urltoimage1.com?qs1=foo"
}

imageId	string	Image Id
error	Error object	Present in the Get All Image URLs response only if an error occurred retrieving the image.
height	number	Image height (in pixels). In the Get All Image URLs request, this (optional) attribute represents requested height; in the response, it represents actual height of the image returned. (See List Image URLs.)
url	string	Temporary URL that can be used to retrieve the image. This attribute can be present in a response but is never specified in a request.
width	number	Image width (in pixels). In the Get All Image URLs request, this (optional) attribute represents requested width; in the response, it represents actual width of the image returned. (See List Image URLs.)

ImageUrlMap Object

imageUrls	ImageUrl[]	Array of ImageUrl objects
urlExpiresInMillis	number	Milliseconds before the URLs within imageUrls expire

Add Image to Cell

Example request: add image to cell

curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages?altText=my%20image' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: image/jpeg" \
-H 'Content-Disposition: attachment; filename="picture.jpg"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @picture.jpg

// Enable FileStream
var fs = require("fs")

// Set options
var options = {
  sheetId: 1696831624483716,
  rowId: 1049441315358596,
  columnId: 74761903175665540,
  fileSize: 458,    // Must be exact bytes; no rounding
  fileName: "img_pl_decisionshapesHold.png",
  fileStream: fs.createReadStream("/Users/jroe/Documents/images/img_pl_decisionshapesHold.png"),
  queryParameters: {
    "altText": "Caution sign",
    "overrideValidation": true
  }
 };

 // Add image to cell
 smartsheet.sheets.addImageToCell(options)
  .then(function(image) {
    console.log(image);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set options
Image image = new Image
  { 
    AltText = "Caution Sign",
    Height = 16,
    Width = 16
  };

smartsheet.SheetResources.RowResources.CellResources.AddImageToCell(
  1696831624483716, // sheetId
  1049441315358596, // rowId
  74761903175665540, // columnId
  "/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png",
  "image"
);

// Set options
Image image = new Image()
  .setAltText("Caution sign")
  .setHeight(16L)
  .setWidth(16L);

smartsheet.sheetResources().rowResources().cellResources().addImageToCell(
  1639534409607044L,      // sheetId
  1049441315358596L,      // rowId
  74761903175665540L,      // columnId
  "/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png",
  "image"
);

sheet_id = 1696831624483716
column_id = 74761903175665540
row_id = 1049441315358596
caution_pic = "/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png"
file_type = "png"
smartsheet_client.Cells.add_image_to_cell(sheet_id, row_id, column_id, caution_pic, file_type)

# Sample 1: Add image from path
response = smartsheet.sheets.cells.add_image_from_path(
  sheet_id: 1696831624483716,
  row_id: 1049441315358596,
  column_id: 74761903175665540,
  path: '/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png'
)
new_image = response[:result]

# Sample 2: Add image
filename = '/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png'
file = File.open(filename)
file_length = File.size(filename)

response = smartsheet.sheets.cells.add_image(
  sheet_id: 1696831624483716,
  row_id: 1049441315358596,
  column_id: 74761903175665540,
  file: file,
  filename: filename,
  file_length: file_length
)
new_image = response[:result]

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
        "id": 6039340093597572,
        "rowNumber": 6,
        "siblingId": 1535740466227076,
        "expanded": true,
        "createdAt": "2017-08-28T21:29:16Z",
        "modifiedAt": "2017-08-30T08:10:47Z",
        "cells": []
    }],
    "version": 19
}

POST /sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages

Uploads an image to the specified cell within a sheet.

Headers	See Simple Uploads for information about required headers.
Parameters	altText (optional): url-encoded alternate text for the image overrideValidation (optional): You may use the query string parameter overrideValidation with a value of true to allow a cell value outside of the validation limits. You must specify strict with a value of false to bypass value type checking.
Request Body	Binary content for the file
Returns	Result object
Access Scope	WRITE_SHEETS

Download Cell Image

Example request: download cell image

// Steps 1 and 2: Locate the cell and obtain the imageId
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \

// In the response, note the columnId and ImageId
// You might also save the altText for Step 4
{
    "cells": [{
        "columnId": 6800865311909764,
        "image": {
            "id": "nQCn-Bm2ncwqsw_FX1XI_w",
            "height": 932,
            "width": 1562,
            "altText": "stanley hotel.png"
        }
    }]
}

// Step 3: Obtain a temporary image URL
curl https://api.smartsheet.com/2.0/imageurls \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"imageId": "nQCn-Bm2ncwqsw_FX1XI_w","height":40,"width": 20}]'

// In the response, note the URL and its expiration time
{
  "urlExpiresInMillis": 1800000,
  "imageUrls": [
    {
      "imageId": "nQCn-Bm2ncwqsw_FX1XI_w",
      "url": "https://aws.smartsheet.com/storageProxy/image/images/OMB9hAConFbhUdJMQ5czQEkwAj1-ErW-sXz3Dr4nDfE?expirationDate=2017-07-25T22%3A13%3A07%2B0000&height=40&width=20&hmac=e%2BfIb0ffUK%2BZeA2hbGx%2Fj8YcWUY%3D"
    }
  ]
}

// Step 4: Download the image
curl -o "stanley_hotel.png" "https://aws.smartsheet.com/storageProxy/image/images/OMB9hAConFbhUdJMQ5czQEkwAj1-ErW-sXz3Dr4nDfE?expirationDate=2017-07-25T22%3A01%3A33%2B0000&height=40&width=20&hmac=5t%2FHs9%2BXTk5cNhyDax9ZgcbepKI%3D"

var fs = require('fs');
var request = require('request');

var sheetId = 1639534409607044;
var rowId = 3344087179913092;
var columnId = 1735559124150148;

//  Step 1: Identify the cell that contains an image

smartsheet.sheets.getRow({
  sheetId: sheetId,
  rowId: rowId
}).then(row => {
  var cell = row.cells.find(cell => cell.columnId === columnId);

// Step 2: Get image info from cell

  var image = cell.image;
  var imageId = image.id;
  var localFileName = image.altText;

// Step 3: Build list of image URLs

smartsheet.images.listImageUrls({
    body: [{imageId: imageId}]
  }).then(result => {
    var imageUrl = result.imageUrls[0].url;

// Step 4: Download the image

    request(imageUrl).pipe(fs.createWriteStream(localFileName));
  });
});

sheetId = 1639534409607044;
rowId = 3344087179913092;
columnId = 1735559124150148;

//  Step 1: Identify the cell that contains an image
Row row = smartsheet.SheetResources.RowResources.GetRow(
  sheetId,
  rowId,
  null,
  null);
Cell cell = row.Cells.First(c => c.ColumnId == columnId);

// Step 2: Get image info from cell
Image image = cell.Image;
string imageId = image.Id;
string localFileName = image.AltText;

// Step 3: Build list of image urls
ImageUrl[] imageUrls = new ImageUrl[] { new ImageUrl { ImageId = imageId } };

string temporaryUrl = smartsheet.ImageUrlResources.GetImageUrls(imageUrls).ImageUrls[0].Url;

// Step 4: Download the image
System.Net.WebClient client = new System.Net.WebClient();
client.DownloadFile(temporaryUrl, localFileName);

long sheetId = 5670346721388420L;
long rowId = 3344087179913092L;
long columnId = 1735559124150148L;

//  Step 1: Identify the cell that contains an image
Row row = smartsheet.sheetResources().rowResources().getRow(
  sheetId,
  rowId,
  null,
  null);
Cell cell = row.getCells().stream().filter(c -> c.getColumnId() == columnId).findFirst().orElse(null);

// Step 2: Get image info from cell
Image image = cell.getImage();
String imageId = image.getId();
String localFileName = image.getAltText();

// Step 3: Build list of image urls
ImageUrl imageUrl = new ImageUrl();
imageUrl.setImageId(imageId);
List<ImageUrl> imageUrls = Arrays.asList(imageUrl);

String temporaryUrl = smartsheet.imageUrlResources().getImageUrls(imageUrls).getImageUrls().get(0).getUrl();

// Step 4: Download the image
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet(temporaryUrl);
CloseableHttpResponse response = httpclient.execute(httpget);
HttpEntity entity = response.getEntity();
FileOutputStream fos = new FileOutputStream(localFileName);
entity.writeTo(fos);
fos.close();

sheetId = 1639534409607044
rowId = 3344087179913092
columnId = 1735559124150148

# Steps 1 and 2: Locate the cell and obtain the imageId
row = smartsheet_client.Sheets.get_row(sheet_id, row_id)
cell = row.get_column(column_id)
image = cell.image
image_id = image.id

# Automate using Alt Text as the file name
filename = getattr(image, 'alt_text', default_filename)

# Step 3: Obtain a temporary image URL
imageUrl = smartsheet.models.ImageUrl( { "imageId": image_id } )
response = smartsheet_client.Images.get_image_urls([imageUrl])
url = response.image_urls[0].url

# Step 4: Download the image
import requests
response = requests.get(url)
if response.status_code == 200:
  with open(filename, 'wb') as f:
    f.write(response.content)

require 'open-uri'

sheet_id = 1639534409607044
row_id = 3344087179913092
column_id = 1735559124150148
default_filename = 'my_image.png'

# Steps 1 and 2: Locate the cell and obtain the imageId
row = smartsheet.sheets.rows.get(sheet_id: sheet_id, row_id: row_id)
cell = row[:cells].select { |cell| cell[:column_id] == column_id }.first
image = cell[:image]
image_id = image[:id]

# Automate using Alt Text as the file name
filename = image[:alt_text] || default_filename

# Step 3: Obtain a temporary image URL
response = smartsheet.sheets.list_image_urls(body: [{image_id: image_id}])
url = response[:image_urls][0][:url]

# Step 4: Download the image
image_download = open(url)
IO.copy_stream(image_download, filename)

Downloading a cell image is a multi-step process. This sample downloads a cell image to a local file. The cell is specified by sheet Id, row Id, and column Id.

Click the appropriate language tab in the rightmost pane to see sample code.

Step 1. Locate the cell

Get the desired row, then locate the desired cell based on the column Id.

Step 2. Obtain the image Id

Cell images are identified by an image Id, which is stored in a cell Image object. (The image Id is the key to the image and should be kept secure.)

When a user uploads an image to a cell, Smartsheet uses the original file name as the image "alt text." This example uses that alt text value as the local file name.

Step 3. Obtain a temporary image URL

The POST /imageurls command creates a temporary URL that you can use to download the image. The URL expires after a short time, which is reported in the response.

Step 4. Download the image

Once you have the URL, issue a standard HTTP GET to download the image and save as a local file.

List Image URLs

Example request: list image URLs

curl https://api.smartsheet.com/2.0/imageurls \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"imageId": "e1znCxhuZo_soEJtUmmX_A","height":40,"width": 20},{"imageId": "g2jdKdfhQa_abKJmPnhC_B","height":100,"width": 50}]'

// Set options
var options = {
  body: [{
    imageId: "jpbGklqdfZuL4Jw-kZhdZA",
    width: 256,
    height: 256
  }]
};

// List image URLs
smartsheet.images.listImageUrls(options)
  .then(function(temporaryUrls) {
    console.log(temporaryUrls);
  })
  .catch(function(error) {
    console.log(error);
  });

// Build list of image urls
ImageUrl[] imageUrls = new ImageUrl[] { new ImageUrl { ImageId = "jpbGklqdfZuL4Jw-kZhdZA" } };

string temporaryUrl = smartsheet.ImageUrlResources.GetImageUrls(imageUrls).ImageUrls[0].Url;

// Build list of image urls
ImageUrl imageUrl = new ImageUrl()
  .setImageId("jpbGklqdfZuL4Jw-kZhdZA");
List<ImageUrl> imageUrls = Arrays.asList(imageUrl);

String temporaryUrl = smartsheet.imageUrlResources().getImageUrls(imageUrls).getImageUrls().get(0).getUrl();

imageUrl = smartsheet.models.ImageUrl(
  {
    "imageId": 'jpbGklqdfZuL4Jw-kZhdZA',
    "height": 256,
    "width": 256
  }
)

response = smartsheet_client.Images.get_image_urls([imageUrl])
url = response.image_urls[0].url

body = [
  {
    image_id: 'jpbGklqdfZuL4Jw-kZhdZA',
    height: 100,
    width: 100
  }
]

image_urls = smartsheet.sheets.list_image_urls(
  body: body
)

Example response

{
  "urlExpiresInMillis": 1800000,
  "imageUrls": [{
    "imageId": "jpbGklqdfZuL4Jw-kZhdZA",
    "url": "https://urltoimage1.com?qs1=foo"
  },
  {
    "imageId": "g2jdKdfhQa_abKJmPnhC_B",
    "error": {
      "errorCode": 5001,
      "message": "You do not have permission to view this image."
  }}]
}

POST /imageurls

Gets a list of URLs that can be used to retrieve the specified cell images.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Array of ImageUrl objects, with the following attributes: imageId (required) height (optional) width (optional) Each image in the response is sized according to which dimensions were specified by the request: If neither height nor width is specified, the image is returned in its original size. If both height and width are specified, image is sized using those measurements. If either height or width is specified (that is, one or the other -- not both), the image is automatically scaled using that measurement. Additionally, the following rules apply: If the requested image size is less than or equal to the actual image size, the returned image size matches the requested size. If the requested image size is larger than the actual image size, the returned image size matches the actual image size.
Returns	ImageUrlMap object
Access Scope	READ_SHEETS

To retrieve images, see the workflow in Download Cell Image.

Remove Image from Cell

To remove an image from a cell (and set cell contents to either empty or to another value), use the Update Rows operation to set cell.value to the new value.

Update Cell Image

A cell image can be updated as follows:

• To change the alternate text of an image, use the Update Rows operation.
• To replace an existing image with a new image, use the Add Image to Cell operation.
• To add an image to a cell that previously contained another type of data, use the Add Image to Cell operation.

Columns

A column is a component of a sheet or report.

Objects

Column Object

Example: Column object

{
  "id": 7960873114331012,
  "version": 2,
  "index": 4,
  "title": "Interesting Choices",
  "formula": "=data@row",
    "type": "MULTI_PICKLIST",
  "options": [
    "1",
    "Hello, World",
    "100%"
  ],
  "validation": false,
  "width": 150
}

id	number	Column Id
systemColumnType	string	When applicable, one of: AUTO_NUMBER, CREATED_BY, CREATED_DATE, MODIFIED_BY, MODIFIED_DATE. See System Columns.
type	string	One of: ABSTRACT_DATETIME CHECKBOX CONTACT_LIST DATE DATETIME DURATION MULTI_CONTACT_LIST MULTI_PICKLIST PICKLIST PREDECESSOR TEXT_NUMBER See Column Types.
autoNumberFormat	AutoNumberFormat	Present when systemColumnType == AUTO_NUMBER
contactOptions	ContactOption[]	Array of ContactOption objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST
description	string	Column description.
format	string	The format descriptor (see Formatting) Only returned if the include query string parameter contains format and this column has a non-default format applied to it.
formula	string	The formula for a column, if set, for instance =data@row.
hidden	Boolean	Indicates whether the column is hidden
index	number	Column index or position. This number is zero-based.
locked	Boolean	Indicates whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin.
lockedForUser	Boolean	Indicates whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.
options	string[]	Array of the options available for the column
primary	Boolean	Returned only if the column is the Primary Column (value = true)
symbol	string	When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns.
tags	string[]	Set of tags to indicate special columns. Each element in the array is set to one of the following values: CALENDAR_END_DATE CALENDAR_START_DATE CARD_DONE GANTT_ALLOCATION GANTT_ASSIGNED_RESOURCE GANTT_DISPLAY_LABEL GANTT_DURATION GANTT_END_DATE GANTT_PERCENT_COMPLETE GANTT_PREDECESSOR GANTT_START_DATE
title	string	Column title
validation	Boolean	Indicates whether validation has been enabled for the column (value = true)
version	number	Read only. The level of the column type. Each element in the array is set to one of the following values: 0: TEXT_NUMBER, CONTACT_LIST, or PICKLIST 1: MULTI_CONTACT_LIST 2: MULTI_PICKLIST See Versioning and Changes.
width	number	Display width of the column in pixels

ContactOption Object

email	string	A parsable email address.
name	string	Can be a user's name, display name, or free text, such as a job class or TBD.

Add Columns

Example request: add columns

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"title": "New Multi-Picklist Column 1", "type": "MULTI_PICKLIST", "options": ["First", "Second", "Third"], "index": 4} , {"title":"New Date Column", "type":"DATE", "formula": "=data@row", "validation":"true", "index":4},]'
-d '[{"index": 6, "title": "Dropdown Multi Select", "type": "MULTI_PICKLIST", "options": ["Template", "Blog",   "Newsletter",   "Email", "Press Release", "Advertisement"], "validation": false, "width": 150}]'

// Specify new columns
var column = [
  {
    "title": "New Picklist Column 1",
    "type": "PICKLIST",
    "options": [
      "First",
      "Second",
      "Third"
    ],
    "index": 4
  },
  {
    "title": "New Date Column",
    "type": "DATE",
    "formula": "=data@row",
    "validation": true,
    "index": 4
  }
];

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

// Add columns to the sheet
smartsheet.sheets.addColumn(options)
  .then(function(newColumns) {
      console.log(newColumns);
  })
  .catch(function(error) {
      console.log(error);
  });

// Create a column
Column columnA = new Column
{
  Title = "This is a new multi-picklist column",
  Index = 0,
  Type = ColumnType.MULTI_PICKLIST,
  Options = new string[] { "Cat", "Rat", "Bat" }
};

// Create another column
Column columnB = new Column
{
  Title = "New Date Column",
  Formula = "=data@row",
  Index = 4,
  Type = ColumnType.DATE
};

// Add columns to the sheet
IList<Column> addedColumns = smartsheet.SheetResources.ColumnResources.AddColumns(
  2252168947361668,   // sheet Id
  new Column[] { columnA, columnB }
);

// Create columns
Column column1 = new Column()
  .setTitle("New Multi-Picklist Column 1")
  .setType(ColumnType.MULTI_PICKLIST)
  .setIndex(4)
  .setOptions(Arrays.asList("First", "Second", "Third"));

Column column2 = new Column()
  .setTitle("New Date Column")
  .setType(ColumnType.DATE)
  .setFormula("=data@row")
  .setValidation(true)
  .setIndex(4);

// Add columns to the sheet
List<Column> newColumns = smartsheet.sheetResources().columnResources().addColumns(
  2252168947361668L,       // long sheetId
  Arrays.asList(column1, column2)
);

# Create the columns
column1 = smartsheet.models.Column({
  'title': 'New Picklist Column 1',
  'type': 'PICKLIST',
  'options': [
    'First',
    'Second',
    'Third'
  ],
  'index': 4
})

column2 = smartsheet.models.Column({
  'title': 'New Date Column',
  'type': 'DATE',
  'formula': '=data@row',
  'validation': 'True',
  'index': 4
})

# Add columns to the sheet
new_columns = smartsheet_client.Sheets.add_columns(
  2252168947361668,       # sheet_id
  [column1, column2])

# Define options
body = {
  title: 'New Picklist Column 1',
  type: 'PICKLIST',
  options: [
    'First',
    'Second',
    'Third'
  ],
  index: 4
},
{
  title: "New Date Column",
  type: 'DATE',
  formula: 'data@row',
  validation: true,
  index: 4
}

# Add the column
new_columns = smartsheet.sheets.columns.add(
  sheet_id: 2252168947361668,
  body: body
)

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": [
    {
      "id": 9007194052434043,
      "index": 4,
      "title": "New Picklist Column 1",
      "type": "PICKLIST",
      "options": [
        "First",
        "Second",
        "Third"
      ],
      "validation": false,
      "width": 150
    },
    {
      "id": 4503594425063547,
      "index": 4,
      "title": "New Date Column",
      "formula": "=data@row",
      "type": "DATE",
      "validation": true,
      "width": 150
    }
  ]
}

POST /sheets/{sheetId}/columns

Inserts one or more columns into the sheet specified in the URL. This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment.

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

Delete Column

Example request: delete column

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

// Set options
var options = {
  sheetId: 9283173393803140,
  columnId: 0123456789012345
};

// Delete column
smartsheet.sheets.deleteColumn(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.SheetResources.ColumnResources.DeleteColumn(
  9283173393803140,               // sheetId
  0123456789012345                // columnId
);

smartsheet.sheetResources().columnResources().deleteColumn(
  9283173393803140L,       // long sheetId
  0123456789012345L        // long columnId
);

smartsheet_client.Sheets.delete_column(
  9283173393803140,       # sheet_id
  0123456789012345)       # column_id

smartsheet.sheets.columns.delete(
  sheet_id: 9283173393803140,
  column_id: 0123456789012345
)

Example response

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

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

Deletes the column specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_SHEETS

Get Column

Example request: get column

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

// Set options
var options = {
  sheetId: 9283173393803140,
  columnId: 7960873114331012
};

// Get column
smartsheet.sheets.getColumns(options)
  .then(function(column) {
    console.log(column);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include' parameter
Column column = smartsheet.SheetResources.ColumnResources.GetColumn(
  9283173393803140,               // sheetId
  7960873114331012,               // columnId
  null                            // IEnumerable<ColumnInclusion> includes
);

// Sample 2: Specify 'include' parameter with value of "FILTERS"
Column column = smartsheet.SheetResources.ColumnResources.GetColumn(
  9283173393803140,               // sheetId
  7960873114331012,               // columnId
  new ColumnInclusion[] { ColumnInclusion.FILTERS }
);

// Sample 1: Omit 'include' parameter
Column column = smartsheet.sheetResources().columnResources().getColumn(
  9283173393803140L,       // long sheetId
  7960873114331012L,       // long columnId
  null                     // EnumSet<ColumnInclusion> includes
);

// Sample 2: Specify 'include' parameter with value of "FILTERS"
Column column = smartsheet.sheetResources().columnResources().getColumn(
  9283173393803140L,       // long sheetId
  7960873114331012L,       // long columnId
  EnumSet.of(ColumnInclusion.FILTERS)
);

column = smartsheet_client.Sheets.get_column(
  9283173393803140,       # sheet_id
  7960873114331012)       # column_id

column = smartsheet.sheets.columns.get(
  sheet_id: 9283173393803140,
  column_id: 7960873114331012
)

Example response

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

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

Gets the column specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	level (optional): specifies whether new functionality, such as multi-contact data is returned in a backwards-compatible, text format (level=0, default), multi-contact data (level=1), or multi-picklist data (level=2).
Returns	Column object
Access Scope	READ_SHEETS

List Columns

Example request: list columns

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

// Set options
var options = {
  sheetId: 9283173393803140
};

// List columns
smartsheet.sheets.getColumns(options)
  .then(function(columnList) {
    console.log(columnList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit 'include' parameter and pagination parameters
PaginatedResult<Column> columns = smartsheet.SheetResources.ColumnResources.ListColumns(
  9283173393803140,               // sheetId
  null,                           // IEnumerable<ColumnInclusion> include
  null,                           // PaginationParameters
  2                               // int compatibilityLevel
);

// Omit 'include' parameter and pagination parameters
PagedResult<Column> columns = smartsheet.sheetResources().columnResources().listColumns(
  9283173393803140L,                   // long sheetId
  null,                                // EnumSet<ColumnInclusion> includes
  null                                 // PaginationParameters
);

response = smartsheet_client.Sheets.get_columns(
  9283173393803140,       # sheet_id
  include_all=True)
columns = response.data

response = smartsheet.sheets.columns.list(
  sheet_id: 9283173393803140
)
columns = response[:data]

Example response

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

GET /sheets/{sheetId}/columns

Gets a list of all columns belonging to the sheet specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
	level (optional): specifies whether multi-contact data is returned in a backwards-compatible, text format (level=0, default) or as multi-contact data (level=1).
Returns	IndexResult object containing an array of Column objects
Access Scope	READ_SHEETS

Update Column

Example request: update column

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X PUT \
-d '{"title": "New multi-select dropdown column", "index": 0, "type": "MULTI_PICKLIST", "options": ["One", "Two"]}'

// Specify column properties
var column = {
  "index": 0,
  "title": "First Column",
  "type": "PICKLIST",
  "options": ["One", "Two"]
};

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

// Update column
smartsheet.sheets.updateColumn(options)
  .then(function(updatedColumn) {
    console.log(updatedColumn);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify column properties
Column columnSpecification = new Column
{
  Id = 5005385858869124,
  Title = "First Column",
  Index = 0,
  Type = ColumnType.PICKLIST,
  Options = new string[] { "One", "Two"}
};

// Update column
Column updatedColumn = smartsheet.SheetResources.ColumnResources.UpdateColumn(
  2252168947361668,   // sheetId
  columnSpecification
);

// Specify column properties
Column columnSpecification = new Column(5005385858869124L)
  .setTitle("First Column")
  .setIndex(0)
  .setType(ColumnType.PICKLIST)
  .setOptions(Arrays.asList("One", "Two"));

// Update column
Column updatedColumn = smartsheet.sheetResources().columnResources().updateColumn(
  2252168947361668L,   // sheetId
  columnSpecification
);

# Specify column properties
column_spec = smartsheet.models.Column({
  'title': 'First Column',
  'type': 'PICKLIST',
  'options': ["One", "Two"],
  'index': 0
})

# Update column
response = smartsheet_client.Sheets.update_column(
  2252168947361668,       # sheet_id
  5005385858869124,       # column_id
  column_spec)

updated_column = response.result

# Specify column properties
body = {
  title: 'First Column',
  type: 'PICKLIST',
  options: [
    'One',
    'Two'
  ]
}

# Update column
response = smartsheet.sheets.columns.update(
  sheet_id: 2252168947361668,
  column_id: 5005385858869124,
  body: body
)
updated_column = response[:result]

Example response

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

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

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

NOTES:

• You cannot change the type of a Primary column.
• While dependencies are enabled on a sheet, you can't change the type of any special calendar/Gantt columns.
• If the column type is changed, all cells in the column are converted to the new column type and column validation is cleared.

• Type is optional when moving or renaming, but required when changing type or dropdown values.

  Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
  Request Body	A Column object that contains the following attributes: index autoNumberFormat (optional) contactOptions (optional) -- must have set column type to CONTACT_LIST description (optional) format (optional) formula (optional) hidden (optional) locked (optional) options (optional) symbol (optional) systemColumnType (optional) title (optional) type (optional) validation (optional) width (optional)
  Returns	Result object containing the Column object that was modified
  Access Scope	ADMIN_SHEETS

Related Items

Column Types

Example column types

{
    "columns": [{
    "id": 9999137079650180,
    "version": 0,
    "index": 0,
    "title": "Text/Number",
    "type": "TEXT_NUMBER",
    "primary": true,
    "validation": false,
    "width": 150
  },
  {
    "id": 9999736707020676,
    "version": 0,
    "index": 1,
    "title": "Contact Column",
    "type": "CONTACT_LIST",
    "contactOptions": [{
      "name": "ziggy@example.com",
      "email": "ziggy@example.com"
    }],
    "validation": false,
    "width": 150
  },
  {
    "id": 999962382411652,
    "version": 1,
    "index": 2,
    "title": "Multi Contact Column",
    "type": "MULTI_CONTACT_LIST",
    "contactOptions": [{
      "name": "Ziggy Star",
      "email": "ziggy@example.com"
      },
      {
      "name": "Jane Roe",
      "email": "jane.roe@example.com"
      }
    ],
    "validation": false,
    "width": 185
  },
  {
    "id": 9999562009782148,
    "version": 0,
    "index": 3,
    "title": "Date Column",
    "type": "DATE",
    "validation": false,
    "width": 150
  },
  {
    "id": 9999762196096900,
    "version": 0,
    "index": 4,
    "title": "Dropdown Single Select",
    "type": "PICKLIST",
    "options": [
      "Project",
      "Story",
      "Task",
      "Spike",
      "Bug"
    ],
    "validation": false,
    "width": 150
  },
  {
    "id": 9999361823467396,
    "version": 2,
    "index": 5,
    "title": "Dropdown Multi Select",
    "type": "MULTI_PICKLIST",
    "options": [
      "Template",
      "Blog",
      "Newsletter",
      "Email",
      "Press Release",
      "Advertisement"
    ],
    "validation": false,
    "width": 150
  },
  {
    "id": 9999104171726724,
    "version": 0,
    "index": 6,
    "title": "Checkbox",
    "type": "CHECKBOX",
    "validation": false,
    "width": 150
  },
  {
    "id": 9999504544356228,
    "version": 0,
    "index": 7,
    "title": "Symbols",
    "type": "PICKLIST",
    "symbol": "PAIN",
    "options": [
      "No Pain",
      "Mild",
      "Moderate",
      "Severe",
      "Very Severe",
      "Extreme"
    ],
    "validation": false,
    "width": 150
}]}

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

Column Type	Column.type Value	Notes
Checkbox	CHECKBOX	Checkbox, star, and flag types
Contact List	CONTACT_LIST	List containing contacts or roles for a project. NOTE: You can use the contactOptions property to specify a pre-defined list of values for the column, which can also become lanes in card view.
Contact List	MULTI_CONTACT_LIST	List where single cells can contain more than one contact. Only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying. To see email addresses behind the display names, combine an include=objectValue query parameter with a level query parameter.
Date	DATE
Date/Time	ABSTRACT_DATETIME	Represents a project sheet's start and end dates. Only for dependency-enabled project sheets The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) Additionally, the API does not support updating data in the "End Date" column under any circumstance, and does not support updating data in the "Start Date" column if "Predecessor" is set for that row.
Date/Time	DATETIME	Used only by the following system-generated columns: Created (Date) (Column.systemColumnType = CREATED_DATE) Modified (Date) (Column.systemColumnType = MODIFIED_DATE)
Dropdown List	PICKLIST	Custom, RYG, Harvey ball, priority types, etc.
Dropdown List	MULTI_PICKLIST	List where single cells can contain more than one dropdown item. Only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying. To see multi-picklist values behind the display names, combine an include=objectValue query parameter with a level query parameter.
Duration	DURATION	Only for dependency-enabled project sheets The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.)
Predecessor	PREDECESSOR	Defines what must happen first in a project flow. For more information, see the Predecessor object. Only for dependency-enabled project sheets
Text/Number	TEXT_NUMBER

Symbol Columns

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

Symbols for CHECKBOX columns:

Value	Example
FLAG
STAR

Symbols for PICKLIST columns:

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

System Columns

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

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

Comments

A discussion is a container for a number of individual comments in a threaded conversation. For more details, see the Discussion section.​

This section describes operations on an individual comment within a discussion thread.

• To retrieve all discussions and comments for an entire sheet, use List Discussions with the ​query parameter​ include​=comments​.
• To retrieve all discussions and comments associated with a row, use List Row Discussions ​with the​ query parameter​ include​=comments​.

Objects

Comment Object

Example: Comment object

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

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

Add Comment

Example request: add comment (without attachment)

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

// Specify comment
var comment = { "text": "This is a new comment." };

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

// Add comment to discussion
smartsheet.sheets.addDiscussionComment(options)
  .then(function(newComment) {
    console.log(newComment);
  })
  .catch(function(error) {
    console.log(error);
  });

// Create comment
Comment commentSpecification = new Comment
{
  Text = "This is a new comment."
};

// Add comment to discussion
Comment newComment = smartsheet.SheetResources.DiscussionResources.CommentResources.AddComment(
  2252168947361668,               // sheetId
  3962273862576004,               // discussionId
  commentSpecification
);

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

// Add comment to discussion
Comment newComment = smartsheet.sheetResources().discussionResources().commentResources().addComment(
  2252168947361668L,       // long sheetId
  3962273862576004L,       // long discussionId
  commentSpecification
);

response = smartsheet_client.Discussions.add_comment_to_discussion(
  2252168947361668,       # sheet_id
  3962273862576004,       # discussion_id
  smartsheet.models.Comment({
    'text': 'This is a new comment.'
  })
)

body = {
  text: 'This is a new comment.'
}

response = smartsheet.sheets.comments.add(
  sheet_id: 2252168947361668,
  discussion_id: 3962273862576004,
  body: body
)
new_comment = response[:result]

Example request: add comment (with attachment)

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F 'comment={ "text":"This is a new comment." };type=application/json' \
-F "file=@insurance_benefits.pdf;type=application/octet-stream"

// Multipart operations are not supported by the Node SDK. Instead, see instructions to Add Comment, and then Attach File to Comment.

// Create comment
Comment commentSpecification = new Comment
{
  Text = "This is a new comment."
};

// Add comment (with attachment) to discussion
Comment newComment = smartsheet.SheetResources.DiscussionResources.CommentResources.AddCommentWithAttachment(
  2252168947361668,                   // sheetId
  3962273862576004,                   // discussionId
  commentSpecification,
  filePath,
  "application/octet-stream"
);

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

// Add comment (with attachment) to discussion
File file = new File(filePath);
smartsheet.sheetResources().discussionResources().commentResources().addCommentWithAttachment(
  2252168947361668L,       // long sheetId
  3962273862576004L,       // long discussionId
  commentSpecification,
  file,
  "application/octet-stream"
);

# Create comment
comment = smartsheet.models.Comment({
  'text': 'This is a new comment.'
})

# Add comment (with attachment) to discussion
response = smartsheet_client.Discussions.add_comment_to_discussion_with_attachment(
  2252168947361668,           # sheet_id
  3962273862576004,           # discussion_id
  comment,
  ('image.png', open('/path/to/image.png', 'rb'), 'image/png')
)

# Multipart operations are not supported by the Ruby SDK. Instead, see instructions to Add Comment, and then Attach File to Comment.

Example response

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

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

Adds a comment to a discussion.

Creating a Comment without an Attachment

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

Creating a Comment with an Attachment

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

Edit Comment

Example request: edit comment

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X PUT \
-d '{"text":"This is the updated comment text."}'

// Specify text
var body = {
  text: "This is the updated comment text."
};

// Set options
var options = {
  sheetId: 3285357287499652,
  commentId: 7144101943502724,
  body: body
};

// Edit comment
smartsheet.sheets.editComment(options)
  .then(function(updatedComment) {
    console.log(updatedComment);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify edited comment properties
Comment commentSpecification = new Comment
{
  Id = 7144101943502724,
  Text = "This is the updated comment text"
}

// Edit comment
Comment updatedComment = smartsheet.SheetResources.DiscussionResources.CommentResources.UpdateComment(
  3285357287499652,          // sheetId
  commentSpecification
);

[todo]

comment = smartsheet_client.Discussions.update_comment(
  3285357287499652,       # sheet_id
  7144101943502724,       # comment_id
  smartsheet.models.Comment({
    'text': 'This is the updated comment text'}))

body = {
  text: 'This is the updated comment text'
}

response = smartsheet.sheets.comments.update(
  sheet_id: 3285357287499652,
  comment_id: 7144101943502724,
  body: body
)
updated_comment = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "id": 7144101943502724,
    "discussionId": 4503677744506756,
    "text": "This is the updated comment text.",
    "createdBy": {
      "name": "John Doe",
      "email": "john.doe@smartsheet.com"
    },
  "createdAt": "2013-01-10T13:43:26Z",
  "modifiedAt": "2013-01-12T19:00:26Z"
  },
  "version": 18
}

PUT /sheets/{sheetId}/comments/{commentId}

Updates the text of a comment. NOTE: Only the user that created the comment is permitted to update it.

Updating a Comment

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

Delete Comment

Example request: delete comment

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

// Set options
var options = {
  sheetId: 2252168947361668,
  commentId: 4952999001909124
};

// Delete comment
smartsheet.sheets.deleteComment(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.SheetResources.CommentResources.DeleteComment(
  2252168947361668,           // sheetId
  4952999001909124            // commentId
);

smartsheet.sheetResources().commentResources().deleteComment(
  2252168947361668L,       // long sheetId
  4952999001909124L        // long commentId
);

smartsheet_client.Discussions.delete_discussion_comment(
  2252168947361668,       # sheet_id
  4952999001909124)       # comment_id

smartsheet.sheets.comments.delete(
  sheet_id: 2252168947361668,
  comment_id: 4952999001909124
)

Example response

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

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

Deletes the comment specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

Get Comment

Example request: get comment

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

// Set options
var options = {
  sheetId: 2252168947361668,
  commentId: 48569348493401200
};

// Get comment
smartsheet.sheets.getComment(options)
  .then(function(comment) {
    console.log(comment);
  })
  .catch(function(error) {
    console.log(error);
  });

Comment comment = smartsheet.SheetResources.CommentResources.GetComment(
  2252168947361668,               // sheetId
  48569348493401200               // commentId
);

Comment comment = smartsheet.sheetResources().commentResources().getComment(
  2252168947361668L,       // long sheetId
  4856934849340120L        // long commentId
);

comment = smartsheet_client.Discussions.get_discussion_comment(
  2252168947361668,       # sheet_id
  4856934849340120)       # comment_id

comment = smartsheet.sheets.comments.get(
  sheet_id: 2252168947361668,
  comment_id: 4856934849340120
)

Example response

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

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

Gets the comment specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Comment object
Access Scope	READ_SHEETS

Related Items

A comment can contain one or more attachments.

Comment Attachments

For details about working with a comment's attachments, see Attachments.

Contacts

A contact is a user's personal contact in Smartsheet (as described in the Help Center article, Managing Contacts).

Objects

Contact Object

Example: Contact object

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

id	string	Contact Id
email	string	Contact's email address
name	string	Contact's full name

Get Contact

Example request: get contact

curl https://api.smartsheet.com/2.0/contacts/{contactId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {id: "AAAAATYU54QAD7_fNhTnhA"};

// Get contact
smartsheet.contacts.getContact(options)
  .then(function(contact) {
    console.log(contact);
  })
  .catch(function(error) {
    console.log(error);
  });

Contact contact = smartsheet.ContactResources.GetContact(
  "AAAAATYU54QAD7_fNhTnhA"      // string contactId
);

Contact contact = smartsheet.contactResources().getContact(
  "AAAAATYU54QAD7_fNhTnhA"      // string contactId
);

contact = smartsheet_client.Contacts.get_contact(
  'AAAAATYU54QAD7_fNhTnhA')       # contact_id

contact = smartsheet.contacts.get(
  contact_id: 'AAAAATYU54QAD7_fNhTnhA'
)

Example response

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

GET /contacts/{contactId}

Gets the specified contact.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- comma-separated list of elements to copy: profileImage -- includes an Image object
Returns	Contact object
Access Scope	READ_CONTACTS

List Contacts

Example request: list contacts

curl https://api.smartsheet.com/2.0/contacts \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

smartsheet.contacts.listContacts({})
  .then(function(contactsList) {
    console.log(contactsList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Contact> contacts = smartsheet.ContactResources.ListContacts(
  null                // PaginationParameters
);

// Omit pagination parameters
PagedResult<Contact> contacts = smartsheet.contactResources().listContacts(
  null        // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Contacts.list_contacts(include_all=True)
contacts = response.data

# Sample 2: Paginate the list (100 contacts per page)
response = smartsheet_client.Contacts.list_contacts(
  page_size=100,
  page=1)
pages = response.total_pages
contacts = response.data

response = smartsheet.contacts.list
contacts = response[:data]

Example response

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

GET /contacts

Gets a list of the user's Smartsheet contacts.

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

Cross-sheet References

To create a formula that references data in another sheet, you must first create a cross-sheet reference between the detail sheet and the source sheet. That reference must also define the cell range.

Once you have created the cross-sheet reference, you can use the reference name in any formula on the detail sheet. To create the formula, use Add Rows or Update Rows.

Cross-sheet references that are not used by any formula are automatically deleted after two hours.

Objects

CrossSheetReference Object

Example: CrossSheetReference object

{
  "id": 6530408486594436,
  "status": "OK",
  "name": "Sample Reference Sheet Range 1",
  "sourceSheetId": 3285357287499652,
  "startRowId": 1646404963723140,
  "endRowId": 1646404963723140,
  "startColumnId": 6800865311909764,
  "endColumnId": 6800865311909764
}

id	long	Cross-sheet reference Id, guaranteed unique within referencing sheet.
endColumnId	long	Defines ending edge of range when specifying one or more columns. To specify an entire column, omit the startRowId and endRowId parameters.
endRowId	long	Defines ending edge of range when specifying one or more rows. To specify an entire row, omit the startColumnId and endColumnId parameters.
sourceSheetId	long	Sheet Id of source sheet.
startColumnId	long	Defines beginning edge of range when specifying one or more columns. To specify an entire column, omit the startRowId and endRowId parameters.
startRowId	long	Defines beginning edge of range when specifying one or more rows. To specify an entire row, omit the startColumnId and endColumnId parameters.
name	string	Friendly name of reference. Auto-generated unless specified in Create Cross-sheet References.
status	string	One of the following values: If the request succeeded: OK: the reference is in a good state If the request failed: BLOCKED: a reference is downstream of a circular issue BROKEN: the data source location was deleted (either a column, row, or sheet) CIRCULAR: the formula reference is self referencing and cannot be resolved DISABLED: updating of the reference is temporarily disabled due to maintenance INVALID/UNKNOWN: the reference is new and has not been validated NOT_SHARED: no common shared users

Create Cross-sheet References

Example request: create cross-sheet references

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/crosssheetreferences \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{
    "name": "Sample Time Log Sheet Range 1",
    "sourceSheetId": 154378742065028,
    "startRowId": 4089096300717956,
    "endRowId": 2681721417164676,
    "startColumnId": 824812248557444,
    "endColumnId": 824812248557444
}'

var body = {
  name: "my cross sheet reference",
  sourceSheetId: 154378742065028,
  startRowId: 4089096300717956,
  endRowId: 2681721417164676,
  "startColumnId": 824812248557444,
    "endColumnId": 824812248557444
};

smartsheet.sheets.createCrossSheetReference({sheetId: 456745674567, body: body})
  .then((result) => {
    console.log("success");
    console.log(JSON.stringify(result));
  })
  .catch((error) => {
    console.log("error");
    console.log(JSON.stringify(error));
  });

CrossSheetReference xref = new CrossSheetReference();
xref.Name = "Sample Time Log Sheet Range 1";
xref.SourceSheetId = 154378742065028;
xref.StartRowId = 4089096300717956;
xref.EndRowId = 2681721417164676;
xref.StartColumnId = 824812248557444;
xref.EndColumnId = 824812248557444;
CrossSheetReference newXRef = smartsheet.SheetResources.CrossSheetReferenceResources.CreateCrossSheetReference(
    1755440242550660,   //sheetId
    xref
  );

CrossSheetReference xref = new CrossSheetReference();
xref.setName("Sample Time Log Sheet Range 1");
xref.setSourceSheetId(154378742065028L);
xref.setStartRowId(4089096300717956L);
xref.setEndRowId(2681721417164676L);
xref.setStartColumnId(824812248557444L);
xref.setEndColumnId(824812248557444L);

CrossSheetReference newXRef = smartsheet.sheetResources().crossSheetReferenceResources().createCrossSheetReference(
    1755440242550660,   //sheetId
    xref
  );

xref = smartsheet.models.CrossSheetReference({
    'name': 'Sample Time Log Sheet Range 1',
    'source_sheet_id': 154378742065028,
    'start_row_id': 4089096300717956,
    'end_row_id': 2681721417164676,
    'start_column_id': 824812248557444,
    'end_column_id': 824812248557444
})
result = smartsheet_client.Sheets.create_cross_sheet_reference(
  1755440242550660, xref)

smartsheet.sheets.cross_sheet_references.create(
  sheet_id: 8157685695702916,
  body: {
    name: "Sample Time Log Sheet Range 1",
    source_sheet_id: 154378742065028,
    start_row_id: 4089096300717956,
    end_row_id: 2681721417164676,
    start_column_id: 824812248557444,
    end_column_id: 824812248557444
  }
)

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "name": "Sample Time Log Sheet Range 1",
    "sourceSheetId": 154378742065028,
    "startRowId": 4089096300717956,
    "endRowId": 2681721417164676,
    "startColumnId": 824812248557444,
    "endColumnId": 824812248557444
  }
}

POST /sheets/{sheetId}/crosssheetreferences

Adds a cross-sheet reference between two sheets and defines the data range for formulas. Each distinct data range requires a new cross-sheet reference.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	CrossSheetReference object with the following attributes: sourceSheetId: sheetId for data source Either two or all of the following: endColumnId: Defines ending edge of range when specifying one or more columns. Must be used with startColumnId. endRowId: Defines ending edge of range when specifying one or more rows. Must be used with startRowId. startColumnId: Defines beginning edge of range when specifying one or more columns. Must be used with endColumnId. startRowId: Defines beginning edge of range when specifying one or more rows. Must be used with endRowId. name (optional): unique name for reference. If you omit this parameter, Smartsheet will autogenerate a name.
Returns	Result object containing a CrossSheetReference object, corresponding to what was specified in the request.
Access Scope	CREATE_SHEETS

Get Cross-sheet Reference

Example request: get cross-sheet references

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

smartsheet.sheets.getCrossSheetReference({sheetId: 9283173393803140, crossSheetReferenceId: 8157685695702916})
  .then((result) => {
    console.log("success");
    console.log(JSON.stringify(result));
  })
  .catch((error) => {
    console.log("error");
    console.log(JSON.stringify(error));
  });

CrossSheetReference xref = smartsheet.SheetResources.CrossSheetReferenceResources.GetCrossSheetReference(
    9283173393803140, // sheetId
    8157685695702916  // crossSheetReferenceId
  );

CrossSheetReference xref = smartsheet.sheetResources().crossSheetReferenceResources().getCrossSheetReference(
    9283173393803140L, // sheetId
    8157685695702916L  // crossSheetReferenceId
  );

result = smartsheet_client.Sheets.get_cross_sheet_reference(
    9283173393803140, # sheet_id
    8157685695702916  # cross_sheet_reference_id
  )

smartsheet.sheets.cross_sheet_references.get(
  sheet_id: 9283173393803140,
  cross_sheet_reference_id: 8157685695702916
)

Example response

{
  "id": 8157685695702916,
  "status": "OK",
  "name": "Sample Time Log Sheet Range 1",
  "sourceSheetId": 154378742065028,
  "startRowId": 4089096300717956,
  "endRowId": 2681721417164676,
  "startColumnId": 824812248557444,
  "endColumnId": 824812248557444
}

GET /sheets/{sheetId}/crosssheetreferences/{crossSheetReferenceId}

Gets the cross-sheet reference specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	CrossSheetReference object
Access Scope	READ_SHEETS

List Cross-sheet References

Example request: list cross-sheet references

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

smartsheet.sheets.listCrossSheetReferences({sheetId: 9283173393803140})
  .then((result) => {
    console.log("success");
    console.log(JSON.stringify(result));
  })
  .catch((error) => {
    console.log("error");
    console.log(JSON.stringify(error));
  });

//Sample 1: List all
smartsheet.SheetResources.CrossSheetReferenceResources.ListCrossSheetReferences(
    9283173393803140, // sheetId
    null              // PaginationParameters
  );

//Sample 2: Paginate the list
PaginationParameters paginationParameters = new PaginationParameters(
    false,  // includeAll
    100,    // pageSize
    1       // page
  );
smartsheet.SheetResources.CrossSheetReferenceResources.ListCrossSheetReferences(
    9283173393803140,   // sheetId
    paginationParameters
  );

//Sample 1: List all
smartsheet.sheetResources().crossSheetReferenceResources().listCrossSheetReferences(
  9283173393803140L,  // sheetId
  null    // PaginationParameters
);

//Sample 2: Paginate the list
PaginationParameters paginationParameters = new PaginationParameters(
  false,  // includeAll
  100,    // pageSize
  1       // page
);
smartsheet.sheetResources().crossSheetReferenceResources().listCrossSheetReferences(
  9283173393803140L,  // sheetId
  paginationParameters
);

result = smartsheet_client.Sheets.list_cross_sheet_references(
  9283173393803140)

smartsheet.sheets.cross_sheet_references.list(
  sheet_id: 9283173393803140
)

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 6,
  "data": [
    {
      "id": 2545778347534212,
      "status": "OK",
      "name": "Data Sheet Range 1",
      "sourceSheetId": 1244271622809476,
      "startColumnId": 6905486478993284,
      "endColumnId": 545911223936900
    },
    {
      "id": 8157685695702916,
      "status": "OK",
      "name": "Sample Time Log Sheet Range 1",
      "sourceSheetId": 154378742065028,
      "startRowId": 4089096300717956,
      "endRowId": 2681721417164676,
      "startColumnId": 824812248557444,
      "endColumnId": 824812248557444
    }
  ]
}

GET /sheets/{sheetId}/crosssheetreferences

Lists all cross-sheet references for the sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	IndexResult object containing an array of CrossSheetReference objects
Access Scope	READ_SHEETS

Dashboards

Smartsheet Dashboards are a collection of widgets that can contain data from a variety of different data sources (for example, sheets, reports, or custom data). Dashboards were once called Sights(TM) and this name is still present in object names, endpoint paths, and other places.

Objects

Dashboard Object

Example: Dashboard object

{
  "id": 2591554075418573,
  "name": "Test",
  "accessLevel": "OWNER",
  "columnCount": 6,
  "widgets": []
}

id	number	Dashboard Id
accessLevel	string	User's permissions on the dashboard. Valid values: ADMIN OWNER VIEWER
backgroundColor	hex	The hex color, for instance #E6F5FE
columnCount	number	Number of columns that the dashboard contains
createdAt	timestamp	Time of creation
favorite	Boolean	Indicates whether the user has marked the dashboard as a favorite
modifiedAt	timestamp	Time of last modification
name	string	Dashboard name
permalink	string	URL that represents a direct link to the dashboard in Smartsheet
source	source	A Source object indicating the dashboard from which this dashboard was created, if any
widgets	widget[]	Array of Widget objects
workspace	Workspace	A Workspace object, limited to only 2 attributes: id name NOTE: this attribute is only present if the dashboard resides within a workspace.

SightPublish Object

readOnlyFullAccessibleBy	string	Indicates who can access the 'Read-Only Full' view of the published dashboard: ALL -- available to anyone who has the link. ORG -- available only to members of the dashboard owner's Smartsheet organization account. Only returned in a response if readOnlyFullEnabled = true.
readOnlyFullEnabled	Boolean	If true, a rich version of the dashboard is published with the ability to use shortcuts and widget interactions.
readOnlyFullUrl	string	URL for 'Read-Only Full' view of the published dashboard. Only returned in a response if readOnlyFullEnabled = true.

Widget Object

Example: Widget object

{
  "id": 3056651398234562,
  "type": "RICHTEXT",
  "contents": {
    "htmlContent": "<p>This is a test</p>"
  },
  "xPosition": 2,
  "yPosition": 0,
  "width": 2,
  "height": 4,
  "showTitleIcon": false,
  "titleFormat": ",,1,,,,,,,3,,,,,,",
  "version": 1
}

id	number	Widget Id
type	string	Type of widget. See table below to see how UI widget names map to type.
contents	WidgetContent object	Data that specifies the contents of the widget. NOTE: The type of WidgetContent object (and attributes within) depends on the value of widget.type.
height	number	Number of rows that the widget occupies on the dashboard
showTitle	Boolean	True indicates that the client should display the widget title. NOTE: This is independent of the title string which may be null or empty.
showTitleIcon	Boolean	True indicates that the client should display the sheet icon in the widget title
title	string	Title of the widget
titleFormat	string	FormatDescriptor
version	int	Widget version number
viewMode	int	1 indicates content is centered. 2 indicates content is left aligned. Must use a query parameter of level=2 to see this information.
width	number	Number of columns that the widget occupies on the dashboard
xPosition	number	X-coordinate of widget's position on the dashboard
yPosition	number	Y-coordinate of widget's position on the dashboard

UI widget name	type string	Object
Chart	CHART	ChartWidgetContent
Image	IMAGE	ImageWidgetContent
Metric	SHEETSUMMARY or METRIC	CellLinkWidgetContent
Report	GRIDGANTT	ReportWidgetContent
Rich Text	RICHTEXT	RichTextWidgetContent
Shortcut	SHORTCUTICON, SHORTCUTLIST, or SHORTCUT	ShortcutWidgetContent
Title	TITLE	TitleWidgetContent
Web Content	WEBCONTENT	WebContentWidgetContent

CellLinkWidgetContent Object

sheetId	number	The Id of the sheet from which the cell data originates
cellData	CellDataItem[]	Array of CellDataItem objects
columns	Column[]	Array of Column objects
hyperlink	WidgetHyperlink	The widget has when clicked attribute set to that hyperlink (if present and non-null)

CellDataItem Object

columnId	number	Column Id for each item
rowId	number	Row Id for each item
sheetId	number	Sheet Id for each item
objectValue	A string, number, or a Boolean value	The type of data returned depends on the cell type and the data in the cell
cell	Cell	Cell object
dataSource	string	CELL
label	string	Label for the data point. This is either the column name or a user-provided string
labelFormat	string	formatDescriptor
order	integer	The display order for the CellDataItem
profileField	SummaryField	SummaryField object
valueFormat	string	formatDescriptor

ChartWidgetContent Object

reportId	number	Report Id denoting container source, if applicable
sheetId	number	Sheet Id denoting container source, if applicable
axes	Axes[]	Array of Axes objects
hyperlink	WidgetHyperlink	The widget has when clicked attribute set to that hyperlink (if present and non-null)
includedColumnIds	includedColumnIds[]]	Array of columnIds if the range was selected through the UI
legend	string	The location in the widget where Smartsheet renders the legend, for example, RIGHT
selectionRanges	SelectionRange[]	If the source is a sheet
series	Series[]	Array of Series objects

ImageWidgetContent Object

privateId	string	The image private Id
fileName	string	Name of the image file
format	string	formatDescriptor
height	integer	Original height of the image in pixels
hyperlink	WidgetHyperlink	The widget has when clicked attribute set to that hyperlink (if present and non-null). Hyperlinks will have interactionType.
width	integer	Original width of the image in pixels

ReportWidgetContent Object

reportId	number	Report Id denoting container source
htmlContent	string	HTML snippet to render report
hyperlink	WidgetHyperlink	The widget has when clicked attribute set to that hyperlink (if present and non-null). Hyperlinks will have interactionType.

RichTextWidgetContent Object

html	string	The widget content as HTML The Rich Text widget supports the following subset of HTML tags and CSS Styles: HTML a - defines a hyperlink br - inserts a single line break li - defines a list item ol - defines an ordered list p - defines a paragraph ul - defines an unordered list span - defines a section in a document CSS color font-family font-size font-style font-weight text-align text-decoration

SelectionRange Object

sourceColumnId1	number	Defines beginning edge of range when specifying one or more columns.
sourceColumnId2	number	Defines ending edge of range when specifying one or more columns.
sourceRowId1	number	Defines beginning edge of range when specifying one or more rows.
sourceRowId2	number	Defines ending edge of range when specifying one or more rows.

ShortcutWidgetContent Object

shortcutData	ShortcutDataItem[]	Array of ShortcutDataItem objects

ShortcutDataItem Object

attachmentType	string	Attachment type (one of BOX_COM, DROPBOX, EGNYTE, EVERNOTE, FILE, GOOGLE_DRIVE, LINK, ONEDRIVE, or SMARTSHEET)
hyperlink	Hyperlink	Hyperlink object
label	string	Label for the data point
labelFormat	string	formatDescriptor
mimeType	string	MIME type if available for attachment type
order	integer	The display order for the ShortcutWidgetItem object

TitleWidgetContent Object

backgroundColor	hex	The hex color, for instance #E6F5FE
htmlContent	string	HTML snippet to render title

WebcontentWidgetContent Object

url	string	The URL

WidgetHyperlink Object

interactionType	string	Specifies what happens when a user clicks the widget. Valid values: DISTI_COPY -- a distribution link, only available if org has distribution links enabled NONE -- do nothing, no other attribute required SMARTSHEET_ITEM -- open a Smartsheet item that is not the SOURCE_SHEET, must also have one of the following: folderId reportId sheetId sightId workspaceId SOURCE_SHEET -- open the container where the widget data comes from, no other attribute required WEB -- launch the URL, must also have url attribute
folderId	number	If interactionType = SMARTSHEET_ITEM this is the folder to open
reportId	number	If interactionType = SMARTSHEET_ITEM this is the report to open
sheetId	number	If interactionType = SMARTSHEET_ITEM this is the sheet to open
sightId	number	If interactionType = SMARTSHEET_ITEM this is the dashboard to open
url	string	If interactionType = WEB this is the URL to launch
workspaceId	number	If interactionType = SMARTSHEET_ITEM this is the workspace to open

Copy Dashboard

Example request: copy dashboard

curl https://api.smartsheet.com/2.0/sights/{sightId}/copy \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"
-d '{ 
  "destinationType": "workspace", 
  "destinationId": 7960873114331012, 
  "newName": "newDashboardName" 
}' \
-X POST

// Specify new dashboard properties
var body = {
  destinationType: "home",
  newName: "newDashboardName"
};

// Set options
var options = {
  sightId: 6327127650920324,
  body: body
};

// Copy Dashboard
smartsheet.sights.copySight(options)
  .then(function(copiedSight) {
    console.log(copiedSight);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination
{
  DestinationId = 3791509922310020,               // long destinationFolderId
  DestinationType = DestinationType.FOLDER,
  NewName = "newDashboardName"
};

// Copy Dashboard
Sight sight = smartsheet.SightResources.CopySight(
  6327127650920324,                               // long sightId
  destination
);

// Specify destination
ContainerDestination destination = new ContainerDestination()
  .setDestinationType(DestinationType.FOLDER)
  .setDestinationId(3791509922310020L)
  .setNewName("newDashboardName");

// Copy Dashboard
Sight sight = smartsheet.sightResources().copySight(
  6327127650920324L,                          // long sightId
  destination
);

new_sight = smartsheet_client.Sights.copy_sight(
  6327127650920324,                           # sight_id
  smartsheet.models.ContainerDestination({
    'destination_type': 'folder',           # folder, workspace, or home
    'destination_id': 3791509922310020,     # folder_id
    'new_name': 'newDashboardName'
  })
)

# Specify destination
body = {
  destination_type: 'folder',
  destination_id: 3791509922310020,
  new_name: 'newDashboardName'
}

# Copy Dashboard
new_sight = smartsheet.sights.copy(
  sight_id: 6327127650920324,
  body: body
)

Example response

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

POST /sights/{sightId}/copy

Creates a copy of the specified dashboard.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	ContainerDestination object
Returns	Result object containing a Dashboard object for the newly created dashboard, limited to the following attributes: id accessLevel name permalink
Access Scope	CREATE_SIGHTS

Delete Dashboard

Example request: delete dashboard

curl https://api.smartsheet.com/2.0/sights/{sightId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \

// Set options
var options = {
  sightId: 5363568917931908
};

// Delete Dashboard
smartsheet.sights.deleteSight(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.SightResources.DeleteSight(
  5077532685952900            // sightId
);

smartsheet.sightResources().deleteSight(
  3100061023397764L       // long sightId
);

smartsheet_client.Sights.delete_sight(3404239197235076)     # sight_id

smartsheet.sights.delete(
  sight_id: 6327127650920324
)

Example response

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

DELETE /sights/{sightId}

Deletes the dashboard specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	DELETE_SIGHTS

Get Dashboard

Example request: get dashboard

curl https://api.smartsheet.com/2.0/sights/{sightId}?level=4 \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  sightId: 6327127650920324
};

// Get dashboard
smartsheet.sights.getSight(options)
  .then(function(sight) {
    console.log(sight);
  })
  .catch(function(error) {
    console.log(error);
  });

Sight sight = smartsheet.SightResources.GetSight(
  6327127650920324        // long sightId
);

Sight sight = smartsheet.sightResources().getSight(
  6327127650920324L       // long sightId
);

sight = smartsheet_client.Sights.get_sight(
  6327127650920324)     # sightId

sight = smartsheet.sights.get(
  sight_id: 6327127650920324
)

Example response

{
  "id": 2591554075418573,
  "name": "Test",
  "accessLevel": "OWNER",
  "columnCount": 6,
  "widgets": [
    {
      "id": 3056651398234562,
      "type": "RICHTEXT",
      "contents": {
        "htmlContent": "<p>This is a test</p>"
      },
      "xPosition": 2,
      "yPosition": 0,
      "width": 2,
      "height": 4,
      "showTitleIcon": false,
      "titleFormat": ",,1,,,,,,,3,,,,,,",
      "version": 1
    },
    {
      "id": 9996257304487812,
      "type": "METRIC",
      "contents": {
        "type": "METRIC",
        "cellData": [
          {
            "label": "test summary here",
            "labelFormat": ",2,,,,,,,1,,,,,,,1,",
            "valueFormat": ",2,1,,,,1,,1,3,,,,,,1,",
            "order": 0,
            "profileField": {
              "id": 9992738687018884,
              "index": 0,
              "title": "test summary here",
              "type": "TEXT_NUMBER",
              "locked": false,
              "lockedForUser": false,
              "objectValue": "summary content",
              "displayValue": "summary content",
              "createdAt": "2019-10-31T22:01:19Z",
              "modifiedAt": "2019-10-31T22:01:19Z"
            },
            "dataSource": "SUMMARY_FIELD",
            "objectValue": "summary content"
          }
        ],
        "sheetId": 663216503187332,
        "viewMode": 2
      },
      "xPosition": 0,
      "yPosition": 0,
      "width": 15,
      "height": 7,
      "title": "test sheet for charts",
      "showTitleIcon": true,
      "showTitle": true,
      "titleFormat": ",,1,,,,,,,3,,,,,,1,",
      "version": 1
    }
  ]
}

GET /sights/{sightId}

Gets the specified dashboard.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of optional elements to include in the response: source - the Source object for any dashboard that was created from another dashboard, if any
	level (optional): specifies whether new functionality, such as multi-contact data is returned in a backwards-compatible, text format (level=0, default), multi-contact data (level=2), multi-picklist data (level=3), or Metric widget with sheet summary (level=4).
	objectValue (optional) -- when used in combination with a level query parameter, includes the email addresses for multi-contact data.
Returns	Dashboard object
Access Scope	READ_SIGHTS

List Dashboards

Example request: list dashboards

curl https://api.smartsheet.com/2.0/sights \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

smartsheet.sights.listSights()
  .then(function(sights) {
    console.log(sights.data);
  })
  .catch(function(error) {
    console.log(error);
  })

PaginatedResult<Sight> sights = smartsheet.SightResources.ListSights(
  null,       // PaginationParameters
  null        // Nullable<DateTime> modifiedSince
);

PagedResult<Sight> sights = smartsheet.sightResources().listSights(
  null,       // PaginationParameters
  null        // Date modifiedSince
);

response = smartsheet_client.Sights.list_sights(include_all=True)
sights = response.data

response = smartsheet.sights.list
sights = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
    {
      "id": 2331373580117892,
      "name": "Sales Dashboard",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJesvSHCQ",
      "createdAt": "2016-01-28T00:24:41Z",
      "modifiedAt": "2016-01-28T20:32:33Z"
    },
    {
      "id": 7397923160909700,
      "name": "Dashboard #2",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJrthEFTG",
      "createdAt": "2016-01-28T01:17:51Z",
      "modifiedAt": "2016-01-28T20:32:27Z"
    }
    ]
}

GET /sights

Gets a list of all dashboards that the user has access to.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	modifiedSince (optional): when specified with a date and time value, response only includes the objects that are modified on or after the date and time specified. If you need to keep track of frequent changes, it may be more useful to use Get Sheet Version.
	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Dashboard objects limited to the following attributes: id accessLevel createdAt modifiedAt name permalink
Access Scope	READ_SIGHTS

Move Dashboard

Example request: move dashboard

curl https://api.smartsheet.com/2.0/sights/{sightId}/move \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"
-d '{ 
  "destinationType": "folder", 
  "destinationId": workspace_or_folder_id 
}' \
-X POST

// Set destination
var body = {
  destinationType: "folder",
  destinationId: 8460057768683396
};

// Set options
var options = {
  sightId: 5077532685952900,
  body: body
};

// Move Dashboard
smartsheet.sights.moveSight(options)
  .then(function(movedSight) {
    console.log(movedSight);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination
{
  DestinationId = 8460057768683396,               // long destinationFolderId
  DestinationType = DestinationType.FOLDER
};

// Move Dashboard
Sight sight = smartsheet.SightResources.MoveSight(
  5077532685952900,                               // long sightId
  destination
);

// Specify destination
ContainerDestination destination = new ContainerDestination()
  .setDestinationType(DestinationType.FOLDER)
  .setDestinationId(7960873114331012L);

// Move Dashboard
Sight sight = smartsheet.sightResources().moveSight(
  4583173393803140L,                          // long sightId
  destination
);

response = smartsheet_client.Sights.move_sight(
  5363568917931908,                           # sight_id
  smartsheet.models.ContainerDestination({
    'destination_type': 'folder',           # folder, workspace, or home
    'destination_id': 8460057768683396      # destination folder_id
  })
)

# Specify destination
body = {
  destination_type: 'folder',
  destination_id: 8460057768683396
}

# Move Dashboard
response = smartsheet.sights.move(
  sight_id: 5363568917931908,
  body: body
)
moved_sight = response[:result]

Example response

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

POST /sights/{sightId}/move

Moves the specified dashboard to a new location.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	ContainerDestination object, limited to the following required attributes: destinationId destinationType
Returns	Result object containing a Dashboard object for the moved dashboard, limited to the following attributes: id accessLevel name permalink
Access Scope	CREATE_SIGHTS

Publish Dashboard

Get Dashboard Publish Status

Example request: get dashboard publish status

curl https://api.smartsheet.com/2.0/sights/{sightId}/publish \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  sightId: 5363568917931908
};

// Get dashboard publish status
smartsheet.sights.getSightPublishStatus(options)
  .then(function(status) {
    console.log(status);
  })
  .catch(function(error) {
    console.log(error);
  });

SightPublish publish = smartsheet.SightResources.GetPublishStatus(
    5363568917931908    // sightId
  );

SightPublish publish = smartsheet.sightResources().getPublishStatus(
      5363568917931908L    // long sightId
  );

status = smartsheet_client.Sights.get_publish_status(
  5363568917931908)       # sight_id

status = smartsheet.sights.get_publish_status(
  sight_id: 5363568917931908
)

Example response

{
  "readOnlyFullEnabled": true,
  "readOnlyFullAccessibleBy": "ALL",
  "readOnlyFullUrl": "https://publish.smartsheet.com/6d35fa6c99334d4892f9591cf6065"
}

GET /sights/{sightId}/publish

Gets the dashboard 'publish' settings.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	SightPublish object
Access Scope	READ_SIGHTS

Set Dashboard Publish Status

Example request: set dashboard publish status

curl https://api.smartsheet.com/2.0/sights/{sightId}/publish \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
-H "Content-Type: application/json"
-X PUT
-d '{ 
  "readOnlyFullEnabled": true, 
  "readOnlyFullAccessibleBy": "ALL" 
}' \

// Specify property to change
var body = {
  readOnlyFullEnabled: false
};

// Set options
var options = {
  sightId: 5363568917931908,
  body: body
};

// Set dashboard publish status
smartsheet.sights.setSightPublishStatus(options)
  .then(function(newStatus) {
    console.log(newStatus);
  })
  .catch(function(error) {
    console.log(error);
  });

SightPublish publish = new SightPublish();
publish.ReadOnlyFullEnabled = true;
smartsheet.SightResources.SetPublishStatus(
  5363568917931908,    // sightId
  publish
);

SightPublish publish = new SightPublish();
publish.setReadOnlyFullEnabled(true);
smartsheet.sightResources().setPublishStatus(
  5363568917931908L,    // long sightId
  publish
);

response = smartsheet_client.Sights.set_publish_status(
  5363568917931908,       # sight_id
  smartsheet.models.SightPublish({
    'read_only_full_enabled': True
  })
)

# Set options
body = {
  read_only_full_enabled: true,
  read_only_full_accessible_by: 'ALL'
}

# Set dashboard publish status
response = smartsheet.sights.set_publish_status(
  sight_id: 5363568917931908,
  body: body
)
status = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "readOnlyFullEnabled": true,
    "readOnlyFullAccessibleBy": "ORG",
    "readOnlyFullUrl": "http://publish.smartsheet.com/9862638d9c444014b5d7a114d436e99d"
  }
}

PUT /sights/{sightId}/publish

Publishes or unpublishes a dashboard.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	SightPublish object limited to the following attributes: readOnlyFullEnabled (required) readOnlyFullAccessibleBy (optional) - set to either ALL or ORG, when readOnlyFullEnabled=true. To publish the dashboard, set readOnlyFullEnabled to true. To unpublish the dashboard, set readOnlyFullEnabled to false.
Returns	Result object containing a SightPublish object
Access Scope	ADMIN_SIGHTS

Share Dashboard

For details about dashboard sharing, see Dashboard Sharing.

Update Dashboard

Example request: update dashboard

curl https://api.smartsheet.com/2.0/sights/{sightId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name": "New Dashboard Name"}'

// Set property to change
var body = {
  name: "New Dashboard Name"
};

// Set options
var options = {
  sightId: 5363568917931908,
  body: body
};

// Update Dashboard
smartsheet.sights.updateSight(options)
  .then(function(updatedSight) {
    console.log(updatedSight);
  })
  .catch(function(error) {
    console.log(error);
  });

Sight sight = smartsheet.SightResources.UpdateSight(
  new Sight {
    Id = 5363568917931908,    // sightId
    Name = "New Dashboard Name"
  }
);

Sight sight = new Sight();
sight.setId(5363568917931908L);    // long sightId
sight.setName("New Dashboard Name");
Sight updatedSight = smartsheet.sightResources().updateSight(sight);

updated_sight = smartsheet_client.Sights.update_sight(
  5363568917931908,           # sight_id
  smartsheet.models.Sight({
    'name': 'New Dashboard Name'
  })
)

# Specify property to change
body = {
  name: 'New Dashboard Name'
}

# Update Dashboard
response = smartsheet.sights.update(
  sight_id: 5363568917931908,
  body: body
)
updated_sight = response[:result]

Example response

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

PUT /sights/{sightId}

Updates (renames) the specified dashboard.

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

Discussions

A discussion is a container for a collection of individual comments within a single thread. A discussion can exist on a row or a sheet.

In the UI, Smartsheet creates a discussion to contain each top-level comment and subsequent replies into a single thread.

Using the API, you can only add a comment to a discussion. If the discussion doesn't already exist, you must create it first.

Objects

Discussion Object

Example: Discussion object

{
  "id": 1848321770841988,
  "title": "Lincoln",
  "comments": [],
  "commentCount": 1,
  "accessLevel": "OWNER",
  "parentType": "ROW",
  "parentId": 3344087179913092,
  "readOnly": false,
  "lastCommentedAt": "2017-06-09T17:04:08Z",
  "lastCommentedUser": {
    "name": "Test User",
    "email": "tester@smartsheet.com"
  },
  "createdBy": {
    "name": "Test User",
    "email": "tester@smartsheet.com"
  }
}

id	number	Discussion Id
parentId	number	Id of the directly associated row or sheet: present only when the direct association is not clear (see List Discussions)
parentType	string	SHEET or ROW: present only when the direct association is not clear (see List Discussions)
accessLevel	string	User's permissions on the discussion
commentAttachments	Attachment[]	Array of Attachment objects
commentCount	number	The number of comments in the discussion
comments	Comment[]	Array of Comment objects
createdBy	User	User object containing name and email of the creator of the discussion
lastCommentedAt	timestamp	Time of most recent comment
lastCommentedUser	User	User object containing name and email of the author of the most recent comment
readOnly	Boolean	Indicates whether the user can modify the discussion
title	string	Read Only. Discussion title automatically created by duplicating the first 100 characters of the top-level comment

Create Discussion on Row

Example request: create discussion on row (without attachment)

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

// Specify discussion
var discussion = {
  "comment": {
    "text": "This text is the body of the first comment"
  }
};

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

// Add discussion to row
smartsheet.sheets.createRowDiscussion(options)
  .then(function(newDiscussion) {
    console.log(newDiscussion);
  })
  .catch(function(error) {
    console.log(error);
  });

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
  Comment = new Comment
    {
      Text = "This text is the body of the first comment"
    },
  Comments = null         // workaround for SDK issue
};

// Add discussion to row
Discussion newDiscussion = smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussion(
  9283173393803140,               // sheetId
  0123456789012345,               // rowId
  discussionSpecification
);

// Create comment
Comment commentSpecification = new Comment()
  .setText("This text is the body of the first comment");

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion()
  .setComment(commentSpecification)
  .setComments(null);     // workaround for SDK issue

// Add discussion to row
Discussion newDiscussion = smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(
  9283173393803140L,       // sheetId
  0123456789012345L,       // rowId
  discussionSpecification
);

response = smartsheet_client.Discussions.create_discussion_on_row(
  9283173393803140,           # sheet_id
  0123456789012345,           # row_id
  smartsheet.models.Discussion({
    'comment': smartsheet.models.Comment({
      'text': 'This text is the body of the first comment'
    })
  })
)

# Set options
body = {
  comment: {
    text: 'This text is the body of the first comment'
  }
}

# Create discussion on row
response = smartsheet.sheets.discussions.create_on_row(
  sheet_id: 4583173393803140,
  row_id: 4293147074291588,
  body: body
)
new_discussion = response[:result]

Example request: create discussion on row (with attachment)

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F 'discussion={ "comment": { "text": "This text is the body of the first comment" } };type=application/json' \
-F "file=@insurance_benefits.pdf;type=application/octet-stream"

// Multipart operations are not supported by the Node SDK. Instead, see instructions to Create Discussion on Row, and then Attach File to Comment.

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
  Comment = new Comment
  {
    Text = "This text is the body of the first comment"
  },
  Comments = null         // workaround for SDK issue
};

// Add discussion to row
Discussion newDiscussion = smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussionWithAttachment(
  9283173393803140,                   // sheetId
  0123456789012345,                   // rowId
  discussionSpecification,
  filePath,
  "application/octet-stream"
);

// Create comment
Comment commentSpecification = new Comment()
  .setText("This text is the body of the first comment");

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion()
  .setComment(commentSpecification)
  .setComments(null);     // workaround for SDK issue

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

// Add discussion to row
Discussion newDiscussion = smartsheet.sheetResources().rowResources().discussionResources().createDiscussionWithAttachment(
  9283173393803140L,       // long sheetId
  0123456789012345L,       // long rowId
  discussionSpecification,
  file,
  "application/octet-stream"
);

# Add discussion to row
response = smartsheet_client.Discussions.create_discussion_on_row_with_attachment(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  smartsheet.models.Discussion({
    'comment': smartsheet.models.Comment({
      'text': 'This text is the body of the first comment'
    })
  }),
  ('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')
)

# Multipart operations are not supported by the Ruby SDK. Instead, see instructions to Create Discussion on Row, and then Attach File to Comment.

Example response

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

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

Creates a new discussion on a row.

Creating a Discussion without an Attachment

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Discussion object with the following attribute: comment (Comment object)
Returns	Result object containing Discussion object for the newly created discussion
Access Scope	WRITE_SHEETS

Creating a Discussion with an Attachment

Headers	See Multipart Uploads for information about headers that are required for multipart requests.
Request Body	Request body should contain parts with the following names: discussion: JSON Discussion object with the following attributes: title (string), must be 100 characters in length or less comment (Comment object) file: (optional) file to attach to the new comment See Multipart Uploads for more information on parts.
Returns	Result object containing a Discussion object for the newly created discussion, which contains a Comment object for the initial discussion comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment.
Access Scope	WRITE_SHEETS

Create Discussion on Sheet

Example request: create discussion on sheet (without attachment)

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

// Specify discussion
var discussion = {
  "comment": {
    "text": "This text is the body of the first comment"
  }
};

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

// Add discussion to sheet
smartsheet.sheets.createDiscussion(options)
  .then(function(newDiscussion) {
    console.log(newDiscussion);
  })
  .catch(function(error) {
    console.log(error);
  });

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
  Comment = new Comment
  {
    Text = "This text is the body of the first comment"
  },
  Comments = null         // workaround for SDK issue
};

// Add discussion to sheet
Discussion newDiscussion = smartsheet.SheetResources.DiscussionResources.CreateDiscussion(
  9283173393803140,                   // sheetId
  discussionSpecification
);

// Create comment
Comment commentSpecification = new Comment()
  .setText("This text is the body of the first comment");

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion()
  .setComment(commentSpecification)
  .setComments(null);     // workaround for SDK issue

// Add discussion to sheet
Discussion newDiscussion = smartsheet.sheetResources().discussionResources().createDiscussion(
  9283173393803140L,       // long sheetId
  discussionSpecification
);

response = smartsheet_client.Discussions.create_discussion_on_sheet(
  9283173393803140,           # sheet_id
  smartsheet.models.Discussion({
    'comment': smartsheet.models.Comment({
      'text': 'This text is the body of the first comment'
    })
  })
)

# Set options
body = {
  comment: {
    text: 'This text is the body of the first comment'
  }
}

# Create discussion on sheet
response = smartsheet.sheets.discussions.create_on_sheet(
  sheet_id: 4583173393803140,
  body: body
)
new_discussion = response[:result]

Example request: create discussion on sheet (with attachment)

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F 'discussion={ "comment": { "text": "This text is the body of the first comment" } };type=application/json' \
-F "file=@file_to_attach;type=application/octet-stream" \

// Multipart operations are not supported by the Node SDK. Instead, see instructions to Create Discussion on Sheet, and then Attach File to Comment.

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
  Comment = new Comment
  {
    Text = "This text is the body of the first comment"
  },
  Comments = null         // workaround for SDK issue
};

// Add discussion (including comment with attachment) to sheet
Discussion newDiscussion = smartsheet.SheetResources.DiscussionResources.CreateDiscussionWithAttachment(
  9283173393803140,                   // sheetId
  discussionSpecification,
  filePath,
  "application/octet-stream"
);

// Create comment
Comment commentSpecification = new Comment()
  .setText("This text is the body of the first comment");

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion()
  .setComment(commentSpecification)
  .setComments(null);     // workaround for SDK issue

File file = new File(filePath);

// Add discussion (including comment with attachment) to sheet
Discussion newDiscussion = smartsheet.sheetResources().discussionResources().createDiscussionWithAttachment(
  9283173393803140L,       // long sheetId
  discussionSpecification,
  file,
  "application/octet-stream"
);

response = smartsheet_client.Discussions.create_discussion_on_sheet_with_attachment(
  9283173393803140,           # sheet_id
  smartsheet.models.Discussion({
    'comment': smartsheet.models.Comment({
      'text': 'This text is the body of the first comment'
    })
  }),
  ('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')
)

# Multipart operations are not supported by the Ruby SDK. Instead, see instructions to Create Discussion on Sheet, and then Attach File to Comment.

Example response

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

POST /sheets/{sheetId}/discussions

Creates a new discussion on a sheet.

Creating a Discussion without an Attachment

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Discussion object with the following attribute: comment (Comment object)
Returns	Result object containing Discussion object for the newly created discussion
Access Scope	WRITE_SHEETS

Creating a Discussion with an Attachment

Headers	See Multipart Uploads for information about headers that are required for multipart requests.
Request Body	Request body should contain parts with the following names: discussion: JSON Discussion object with the following attributes: title (string), must be 100 characters in length or less comment (Comment object) file: (optional) file to attach to the new comment See Multipart Uploads for more information on parts.
Returns	Result object containing a Discussion object for the newly created discussion, which contains a Comment object for the initial discussion comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment.
Access Scope	WRITE_SHEETS

Delete Discussion

Example request: delete discussion

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

// Set options
var options = {
  sheetId: 2252168947361668,
  discussionId: 991393444325252
};

// Delete discussion
smartsheet.sheets.deleteDiscussion(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.SheetResources.DiscussionResources.DeleteDiscussion(
  9283173393803140,               // sheetId
  0123456789012345                // discussionId
);

smartsheet.sheetResources().discussionResources().deleteDiscussion(
  9283173393803140L,       // long sheetId
  0123456789012345L        // long discussionId
);

smartsheet_client.Discussions.delete_discussion(
  9283173393803140,       # sheet_id
  0123456789012345)       # discussion_id

smartsheet.sheets.discussions.delete(
  sheet_id: 4583173393803140,
  discussion_id: 3962273862576004
)

Example response

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

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

Deletes the discussion specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

List Discussions

Example request: list discussions

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

// Set options
var options = {
  sheetId: 3138415114905476
};

// List discussions
smartsheet.sheets.getDiscussions(options)
  .then(function(discussionList) {
    console.log(discussionList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<Discussion> results = smartsheet.SheetResources.DiscussionResources.ListDiscussions(
  9283173393803140,               // sheetId
  null,                           // IEnumerable<DiscussionInclusion> include
  null                            // PaginationParameters
);

// Sample 2: Specify 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true'
PaginatedResult<Discussion> results = smartsheet.SheetResources.DiscussionResources.ListDiscussions(
  9283173393803140,               // sheetId
  new DiscussionInclusion[] { DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS },
  new PaginationParameters(
    true,                       // includeAll
    null,                       // int pageSize
    null)                       // int page
);

// Sample 1: Omit 'include' parameter and pagination parameters
PagedResult<Discussion> results = smartsheet.sheetResources().discussionResources().listDiscussions(
  9283173393803140L,   // long sheetId
  null,                // PaginationParameters
  null                 // EnumSet<DiscussionInclusion> includes
);

// Sample 2: Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters()
  .setIncludeAll(true);

// List discussions (specify 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true')
PagedResult<Discussion> results = smartsheet.sheetResources().discussionResources().listDiscussions(
  9283173393803140L,   // long sheetId
  parameters,
  EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS)
);

# Sample 1: List all
response = smartsheet_client.Discussions.get_all_discussions(
  9283173393803140,       # sheet_id
  include_all=True)
discussions = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Discussions.get_all_discussions(
  9283173393803140,       # sheet_id
  page_size=10,
  page=1)
pages = response.total_pages
discussions = response.data

response = smartsheet.sheets.discussions.list(
  sheet_id: 4583173393803140
)
discussions = response[:data]

Example response

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

GET /sheets/{sheetId}/discussions

Gets a list of all discussions associated with the specified sheet. Remember that discussions are containers for the conversation thread. To see the entire thread, use the include=comments parameter.

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

Get Discussion

Example request: get discussion

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

// Set options
var options = {
  sheetId: 2252168947361668,
  discussionId: 2331373580117892
};

// Get discussion
smartsheet.sheets.getDiscussions(options)
  .then(function(discussion) {
    console.log(discussion);
  })
  .catch(function(error) {
    console.log(error);
  });

Discussion discussion = smartsheet.SheetResources.DiscussionResources.GetDiscussion(
  9283173393803140,               // sheetId
  0123456789012345                // discussionId
);

Discussion discussion = smartsheet.sheetResources().discussionResources().getDiscussion(
  9283173393803140L,       // long sheetId
  0123456789012345L        // long discussionId
);

discussion = smartsheet_client.Discussions.get_discussion(
  9283173393803140,       # sheet_id
  0123456789012345)       # discussion_id

# discussion is an instance of smartsheet.models.Discussion

discussion = smartsheet.sheets.discussions.get(
  sheet_id: 4583173393803140,
  discussion_id: 3962273862576004
)

Example response

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

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

Gets the discussion specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Discussion object
Access Scope	READ_SHEETS

List Row Discussions

Example request: list row discussions

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

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

// List row discussions
smartsheet.sheets.getRowDiscussions(options)
  .then(function(discussionList) {
    console.log(discussionList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<Discussion> results = smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(
  2252168947361668,                   // sheetId
  4293147074291588,                   // rowId
  null,                               // IEnumerable<DiscussionInclusion> include
  null                                // PaginationParameters
);

// Sample 2: Specify 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true'
PaginatedResult<Discussion> results = smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(
  2252168947361668,                   // sheetId
  4293147074291588,                   // rowId
  new DiscussionInclusion[] { DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS },
  new PaginationParameters(
    true,                           // includeAll
    null,                           // int pageSize
    null)                           // int page
);

// Sample 1: Omit 'include' parameter and pagination parameters
PagedResult<Discussion> results = smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(
  2252168947361668L,       // long sheetId
  4293147074291588L,       // long rowId
  null,                    // PaginationParameters
  null                     // EnumSet<DiscussionInclusion> includes
);

// Sample 2: Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters()
  .setIncludeAll(true);

// Get all row discussions (specify 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true')
PagedResult<Discussion> results = smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(
  2252168947361668L,       // long sheetId
  4293147074291588L,       // long rowId
  parameters,
  EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS)
);

# Sample 1: List all
response = smartsheet_client.Discussions.get_row_discussions(
  2252168947361668,               # sheet_id
  4293147074291588,               # row_id
  include_all=True)
discussions = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Discussions.get_row_discussions(
  2252168947361668,               # sheet_id
  4293147074291588,               # row_id
  page_size=10)
pages = response.total_pages          # starts on page 1 by default
discussions = response.data

response = smartsheet.sheets.discussions.list_row_discussions(
  sheet_id: 4583173393803140,
  row_id: 4293147074291588
)
discussions = response[:data]

Example response

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

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

Gets a list of all discussions associated with the specified row. Remember that discussions are containers for the conversation thread. To see the entire thread, use the include=comments parameter.

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

Related Items

A discussion is a collection of one or more comments, each of which may contain attachments.

Discussion Attachments

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

Discussion Comments

For details about working with a discussion's comments, see Comments.

Favorites

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

Objects

Favorite Object

Example: Favorite object

{
  "type": "sheet",
  "objectId": 5897312590423940
}

objectId	number	Id of the favorited item. If type is template, only private sheet-type template Id is allowed.
type	string	One of: folder, report, sheet, sight, template, or workspace

Add Favorites

Example request: add favorites

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

// Specify favorites
var favorites = [
  {
    "type": "sheet",
    "objectId": 8400677765441412
  }
];

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

// Add items to favorites
smartsheet.favorites.addItemsToFavorites(options)
  .then(function(newFavorite) {
    console.log(newFavorite);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify favorites
IList<Favorite> favoritesSpecification = new Favorite[]
{
  new Favorite
  {
    Type = ObjectType.SHEET,
    ObjectId = 8400677765441412
  }
};

// Add items to favorites
IList<Favorite> newFavorite = smartsheet.FavoriteResources.AddFavorites(favoritesSpecification);

// Specify favorites
Favorite favoritesSpecification = new Favorite()
  .setObjectId(8400677765441412L)
  .setType(FavoriteType.SHEET);

// Add items to favorites
List<Favorite> newFavorite = smartsheet.favoriteResources().addFavorites(Arrays.asList(favoritesSpecification));

response = smartsheet_client.Favorites.add_favorites([
  smartsheet.models.Favorite({
    'type': 'sheet',
    'object_id': 8400677765441412
  })
])

# Specify favorites
body = {
  type: 'sheet',
  object_id: 8400677765441412
}

# Add items to favorites
response = smartsheet.favorites.add(
  body: body
)

Example response

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

POST /favorites

Adds one or more items to the user's list of favorite items. This operation supports both single-object and bulk semantics. For more information, see Optional Bulk Operations.

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

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

List Favorites

Example request: list favorites

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

smartsheet.favorites.listFavorites()
  .then(function(favoritesList) {
    console.log(favoritesList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Favorite> results = smartsheet.FavoriteResources.ListFavorites(
  null                // PaginationParameters
);

// Omit pagination parameters
PagedResult<Favorite> results = smartsheet.favoriteResources().listFavorites(
  null        // PaginationParameters
);

response = smartsheet_client.Favorites.list_favorites(include_all=True)
faves = response.data

response = smartsheet.favorites.list
list = response[:data]

Example response

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

GET /favorites

Gets a list of all of the user's favorite items.

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

Remove Favorite

Remove Favorite Folder

Example request: remove favorite folder

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

// Set options
var options = {
  objectId: 2252168947361668
};

// Remove folder from list of favorites
smartsheet.favorites.removeFolderFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.FOLDER,
  new long[] { 2252168947361668 }   // folderId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.FOLDER,
  new HashSet(Arrays.asList(2252168947361668L))      // long folderId
);

smartsheet_client.Favorites.remove_favorites(
  'folder', 
  2252168947361668        # folder_id
)

smartsheet.favorites.remove_folder(
  folder_id: 2252168947361668
)

Example response

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

DELETE /favorites/folder/{folderId}

Removes a single folder from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite Report

Example request: remove favorite report

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

// Set options
var options = {
  objectId: 2252168947361668
};

// Remove report from list of favorites
smartsheet.favorites.removeReportFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.REPORT,
  new long[] { 2252168947361668 }       // reportId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.REPORT,
  new HashSet(Arrays.asList(2252168947361668L))         // long reportId
);

smartsheet_client.Favorites.remove_favorites(
  'report', 
  2252168947361668        # report_id
)

smartsheet.favorites.remove_report(
  report_id: 2252168947361668
)

Example response

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

DELETE /favorites/report/{reportId}

Removes a single report from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite Sheet

Example request: remove favorite sheet

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

// Set options
var options = {
  objectId: 2252168947361668
};

// Remove sheet from list of favorites
smartsheet.favorites.removeSheetFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });   

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.SHEET,
  new long[] { 2252168947361668 }   // sheetId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.SHEET,
  new HashSet(Arrays.asList(2252168947361668L))         // long sheetId
);

smartsheet_client.Favorites.remove_favorites(
  'sheet', 
  2252168947361668        # sheet_id
)

smartsheet.favorites.remove_sheet(
  sheet_id: 2252168947361668
)

Example response

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

DELETE /favorites/sheet/{sheetId}

Removes a single sheet from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite Dashboard

Example request: remove favorite dashboard

curl https://api.smartsheet.com/2.0/favorites/sight/{sightId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  objectId: 6327127650920324
};

// Remove dashboard from list of favorites
smartsheet.favorites.removeSightFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.SIGHT,
  new long[] { 2252168947361668 } // sightId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.SIGHT,
  new HashSet(Arrays.asList(2252168947361668L)) // long sightId
);

smartsheet_client.Favorites.remove_favorites(
  'sight',
  6327127650920324        # sight_id
)

smartsheet.favorites.remove_sight(
  sight_id: 6327127650920324
)

Example response

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

DELETE /favorites/sights/{sightId}

Removes a single dashboard from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite Template

Example request: remove favorite template

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

// Set options
var options = {
  objectId: 2252168947361668
};

// Remove template from list of favorites
smartsheet.favorites.removeTemplateFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.TEMPLATE,
  new long[] { 2252168947361668 }     // templateId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.TEMPLATE,
  new HashSet(Arrays.asList(2252168947361668L))         // long templateId
);

smartsheet_client.Favorites.remove_favorites(
  'template', 
  2252168947361668        # template_id
)

smartsheet.favorites.remove_template(
  template_id: 2252168947361668
)

Example response

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

DELETE /favorites/template/{templateId}

Removes a single template from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite Workspace

Example request: remove favorite workspace

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

// Set options
var options = {
  objectId: 2252168947361668
};

// Remove workspace from list of favorites
smartsheet.favorites.removeWorkspaceFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.WORKSPACE,
  new long[] { 2252168947361668 }   // workspaceId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.WORKSPACE,
  new HashSet(Arrays.asList(2252168947361668L))       // long workspaceId
);

smartsheet_client.Favorites.remove_favorites(
  'workspace', 
  2252168947361668        # workspace_id
)

smartsheet.favorites.remove_workspace(
  workspace_id: 2252168947361668
)

Example response

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

DELETE /favorites/workspace/{workspaceId}

Removes a single workspace from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Multiple Favorites

Remove Multiple Favorite Folders

Example request: remove multiple favorite folders

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

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

// Remove folders from list of favorites
smartsheet.favorites.removeFoldersFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.FOLDER,
  new long[] { 2252168947361668, 2252168947361669 }     // folderIds
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.FOLDER,
  new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L))      // long folderIds
);

smartsheet_client.Favorites.remove_favorites(
  'folder', 
  [2252168947361668, 2252168947361669]        # folder_ids
)

smartsheet.favorites.remove_folders(
  folder_ids: [2252168947361668, 2252168947361669]
)

Example response

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

DELETE /favorites/folder

Removes multiple folders from the user's list of favorite items.

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

Remove Multiple Favorite Reports

Example request: remove multiple favorite reports

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

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

// Remove reports from list of favorites
smartsheet.favorites.removeReportsFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.REPORT,
  new long[] { 2252168947361668, 2252168947361669 }    // reportIds
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.REPORT,
  new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L))      // long reportIds
);

smartsheet_client.Favorites.remove_favorites(
  'report', 
  [2252168947361668, 2252168947361669]        # report_ids
)

smartsheet.favorites.remove_reports(
  report_ids: [2252168947361668, 2252168947361669]
)

Example response

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

DELETE /favorites/report

Removes multiple reports from the user's list of favorite items.

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

Remove Multiple Favorite Sheets

Example request: remove multiple favorite sheets

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

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

// Remove sheets from list of favorites
smartsheet.favorites.removeSheetsFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.SHEET,
  new long[] { 2252168947361668, 2252168947361669 }    // sheetIds
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.SHEET,
  new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L))     // long sheetIds
);

smartsheet_client.Favorites.remove_favorites(
  'sheet', 
  [2252168947361668, 2252168947361669]        # sheet_ids
)

smartsheet.favorites.remove_sheets(
  sheet_ids: [2252168947361668, 2252168947361669]
)

Example Response:

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

DELETE /favorites/sheet

Removes multiple sheets from the user's list of favorite items.

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

Remove Multiple Favorite Dashboards

Example request: remove multiple favorite dashboards

curl 'https://api.smartsheet.com/2.0/favorites/sight?objectIds=sightId1,sightId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  queryParameters: {
    objectIds: '970160371507588,6327427650920324'
  }
};

// Remove dashboard from list of favorites
smartsheet.favorites.removeSightsFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.SIGHT,
  new long[] { 2252168947361668, 3404239197235076 } // sightIds
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.SIGHT,
  new HashSet(Arrays.asList(2252168947361668L, 3404239197235076L)) // long sightIds
);

smartsheet_client.Favorites.remove_favorites(
  'sight',
  [6327127650920324, 3404239197235076]        # sight_ids
)

smartsheet.favorites.remove_sights(
  sight_ids: [6327127650920324, 2591554075418573]
)

Example response

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

DELETE /favorites/sights

Removes multiple dashboards from the user's list of favorite items.

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

Remove Multiple Favorite Templates

Example request: remove multiple favorite templates

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

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

// Remove templates from list of favorites
smartsheet.favorites.removeTemplatesFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.TEMPLATE,
  new long[] { 2252168947361668, 2252168947361669 }     // templateIds
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.TEMPLATE,
  new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L))    // long templateIds
);

smartsheet_client.Favorites.remove_favorites(
  'template', 
  [2252168947361668, 2252168947361669]        # template_ids
)

smartsheet.favorites.remove_templates(
  template_ids: [2252168947361668, 2252168947361669]
)

Example response

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

DELETE /favorites/template

Removes multiple templates from the user's list of favorite items.

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

Remove Multiple Favorite Workspaces

Example request: remove multiple favorite workspaces

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

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

// Remove workspaces from list of favorites
smartsheet.favorites.removeWorkspacesFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.WORKSPACE,
  new long[] { 2252168947361668, 2252168947361669 }    // workspaceIds
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.WORKSPACE,
  new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L))      // long workspaceIds
);

smartsheet_client.Favorites.remove_favorites(
  'workspace', 
  [2252168947361668, 2252168947361669]        # workspace_ids
)

smartsheet.favorites.remove_workspaces(
  workspace_ids: [2252168947361668, 2252168947361669]
)

Example response

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

DELETE /favorites/workspace

Removes multiple workspaces from the user's list of favorite items.

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

Folders

A folder can exist in a user's Sheets folder (Home), in a folder, or in a workspace.

Objects

Folder Object

Example: Folder object

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

id	number	Folder Id
favorite	Boolean	Returned only if the user has marked the folder as a favorite in their "Home" tab (value = true)
folders	Folder[]	Array of Folder objects
name	string	Folder name
permalink	string	URL that represents a direct link to the folder in Smartsheet
reports	Report[]	Array of Report objects
sheets	Sheet[]	Array of Sheet objects
sights	Dashboard[]	Array of Dashboard objects
templates	Template[]	Array of Template objects

Copy Folder

Example request: copy folder

curl 'https://api.smartsheet.com/2.0/folders/{folderId}/copy?include=data'
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
-H "Content-Type: application/json"
-d '{
  "destinationType": "folder",
  "destinationId": 7960873114331012,
  "newName": "newFolderName"
}'
-X POST

// Specify destination information
var body = {
  destinationType: "folder",
  destinationId: 7960873114331012,
  newName: "Folder Copy"
};

// Specify elements to copy
var params = {
  include: "data,discussions",
  skipRemap: "cellLinks"
};

// Set options
var options = {
  folderId: 2252168947361668,
  body: body,
  queryParameters: params
};

// Copy folder
smartsheet.folders.copyFolder(options)
  .then(function(folder) {
    console.log(folder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination {
  DestinationId = 7960873114331012,
  DestinationType = DestinationType.FOLDER,
  NewName = "newFolderName"
};

// Sample 1: Omit 'include' and 'skipRemap' parameters
Folder folder = smartsheet.FolderResources.CopyFolder(
  2252168947361668,               // long folderId
  destination,
  null,                           // IEnumerable<FolderCopyInclusion> include
  null                            // IEnumerable<FolderRemapExclusion> skipRemap
);

// Sample 2: Specify 'include' parameter with value of "DATA", and 'skipRemap' parameter with value of "CELL_LINKS"
Folder folder = smartsheet.FolderResources.CopyFolder(
  2252168947361668,               // long folderId
  destination,
  new FolderCopyInclusion[] {
    FolderCopyInclusion.DATA },
  new FolderRemapExclusion[] {
    FolderRemapExclusion.CELL_LINKS }
);

// Specify destination
ContainerDestination destination = new ContainerDestination()
  .setDestinationType(DestinationType.FOLDER)
  .setDestinationId(7960873114331012L)
  .setNewName("newFolderName");

// Sample 1: Omit 'include' and 'skipRemap' parameters
Folder folder = smartsheet.folderResources().copyFolder(
  2252168947361668L,                      // long folderId
  destination,
  null,                                   // EnumSet<FolderCopyInclusion> includes
  null                                    // EnumSet<FolderRemapExclusion> skipRemap
);

// Sample 2: Specify 'include' parameter with value of "DATA", and 'skipRemap' parameter with value of "CELLLINKS"
Folder folder = smartsheet.folderResources().copyFolder(
  2252168947361668L,                      // long folderId
  destination,
  EnumSet.of(FolderCopyInclusion.DATA),
  EnumSet.of(FolderRemapExclusion.CELLLINKS)
);

response = smartsheet_client.Folders.copy_folder(
  2252168947361668,                           # folder_id
  smartsheet.models.ContainerDestination({
    'destination_id': 7960873114331012,
    'destination_type': 'folder',
    'new_name': 'newFolderName'
  })
)

# Specify destination information
body = {
  destination_type: 'folder',
  destination_id: 7960873114331012,
  new_name: 'newFolderName'
}

# Copy folder
response = smartsheet.folders.copy(
  folder_id: 2252168947361668,
  body: body
)

Example response

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

POST /folders/{folderId}/copy

Creates a copy of the specified folder.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of elements to copy: attachments cellLinks data -- includes formatting discussions -- includes comments filters forms ruleRecipients -- includes notification recipients, must also include rules when using this attribute rules -- includes notifications and workflow rules shares all - deprecated NOTE: Cell history is not copied, regardless of which include parameter values are specified.
	skipRemap (optional) -- comma-separated list of references to NOT re-map for the newly created folder: cellLinks reports sheetHyperlinks sights By default, all cell links, dashboards, reports, and sheet hyperlinks that reference objects in the source folder are re-mapped to reference corresponding objects in the newly created folder. The skipRemap parameter can be specified to change that default behavior: If cellLinks is specified in the skipRemap parameter value, the cell links within the newly created folder continue to point to the original source sheets. If reports is specified in the skipRemap parameter value, the reports within the newly created folder continue to point to the original source sheets. If sheetHyperlinks is specified in the skipRemap parameter value, the sheet hyperlinks within the newly created folder continue to point to the original source sheets. If sights is specified in the skipRemap parameter value, the widgets within each dashboard in the newly created folder continue to point to the original source sheets / reports.
Request Body	ContainerDestination object
Returns	Result object containing a Folder object for the newly created folder
Access Scope	ADMIN_WORKSPACES

Create Folder

A folder can be created in the user's Sheets folder (Home), in another folder, or in a workspace.

Create Folder (Sheets Level)

Example request: create folder (sheets level)

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

// Set folder name
var folder = {
  "name": "New folder"
};

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

// Create folder in "Sheets" folder (Home)
smartsheet.home.createFolder(options)
  .then(function(newFolder) {
    console.log(newFolder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set folder name
Folder folderSpecification = new Folder { Name = "New folder" };

// Create folder in "Sheets" folder (Home)
Folder newFolder = smartsheet.HomeResources.FolderResources.CreateFolder(folderSpecification);

// Set folder name
Folder folderSpecification = new Folder();
folderSpecification.setName("New Folder");

// Create folder in "Sheets" folder (Home)
Folder newFolder = smartsheet.homeResources().folderResources().createFolder(folderSpecification);

new_folder = smartsheet_client.Home.create_folder('New Folder')

body = {
  name: 'New Folder'
}

new_folder = smartsheet.folders.create(body: body)

Example response

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

POST /home/folders

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

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

Create Folder (Subfolder)

Example request: create folder (subfolder)

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

// Set folder name
var folder = {
  "name": "New folder"
};

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

// Create folder in another folder
smartsheet.folders.createChildFolder(options)
  .then(function(newFolder) {
    console.log(newFolder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set folder name
Folder folderSpecification = new Folder { Name = "New folder" };

// Create folder in another folder
Folder newFolder = smartsheet.FolderResources.CreateFolder(
  7960873114331012,               // long destinationFolderId
  folderSpecification
);

// Set folder name
Folder folderSpecification = new Folder();
folderSpecification.setName("New Folder");

// Create folder in another folder
Folder newFolder = smartsheet.folderResources().createFolder(
  7960873114331012L,       // long destinationFolderId
  folderSpecification
);

response = smartsheet_client.Folders.create_folder_in_folder(
  7960873114331012,       # folder_id
  'New folder')

body = {
  name: 'New Folder'
}

new_folder = smartsheet.folders.create_in_folder(
  folder_id: 7960873114331012,
  body: body
)

Example response

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

POST /folders/{folderId}/folders

Creates a folder in the specified folder.

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

Create Folder (Workspace)

Example request: create folder (workspace)

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

// Set folder name
var folder = {
  "name": "New folder"
};

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

// Create folder in a workspace
smartsheet.workspaces.createFolder(options)
  .then(function(newFolder) {
    console.log(newFolder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set folder name
Folder folderSpecification = new Folder { Name = "New folder" };

// Create folder in a workspace
Folder newFolder = smartsheet.WorkspaceResources.FolderResources.CreateFolder(
  1656220827314052,               // long workspaceId
  folderSpecification
);

// Set folder name
Folder folderSpecification = new Folder();
folderSpecification.setName("New Folder");

// Create folder in a workspace
Folder newFolder = smartsheet.workspaceResources().folderResources().createFolder(
  1656220827314052L,       // long workspaceId
  folderSpecification
);

new_workspace = smartsheet_client.Workspaces.create_folder_in_workspace(
  1656220827314052,       # workspace_id
  'New folder')

body = {
  name: 'New Folder'
}

new_folder = smartsheet.folders.create_in_workspace(
  workspace_id: 1656220827314052,
  body: body
)

Example response

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

POST /workspaces/{workspaceId}/folders

Creates a folder in the specified workspace.

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

Delete Folder

Example request: delete folder

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

// Set options
var options = {
  id: 965780272637828 // Id of Folder
};

// Delete folder
smartsheet.folders.deleteFolder(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FolderResources.DeleteFolder(
  965780272637828                 // long folderId
);

smartsheet.folderResources().deleteFolder(
  965780272637828L         // long folderId
);

smartsheet_client.Folders.delete_folder(
  7960873114331012)       # folder_id

smartsheet.folders.delete(
  folder_id: 2252168947361668
)

Example response

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

DELETE /folders/{folderId}

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Get Folder

Example request: get folder

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

// Set options
var options = {
  id: 7116448184199044 // Id of Folder
};

// Get folder
smartsheet.folders.getFolder(options)
  .then(function(folder) {
    console.log(folder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include' parameter
Folder folder = smartsheet.FolderResources.GetFolder(
  7116448184199044,           // long folderId
  null                        // IEnumerable<FolderInclusion> include
);

// Sample 2: Specify 'include' parameter with value of "SOURCE"
Folder folder = smartsheet.FolderResources.GetFolder(
  7116448184199044,           // long folderId
  new FolderInclusion[] {
    FolderInclusion.SOURCE }
);

// Sample 1: Omit 'include' parameter
Folder folder = smartsheet.folderResources().getFolder(
  7116448184199044L,       // long folderId
  null)                    // EnumSet<SourceInclusion> includes
);

// Sample 2: Specify 'include' parameter with value of "SOURCE"
Folder folder = smartsheet.folderResources().getFolder(
  7116448184199044L,       // long folderId
  EnumSet.of(SourceInclusion.SOURCE))
);

folder = smartsheet_client.Folders.get_folder(
  7116448184199044)       # folder_id

folder = smartsheet.folders.get(
  folder_id: 7116448184199044
)

Example response

{
  "id": 7116448184199044,
  "name": "Projects",
  "permalink": "https://app.smartsheet.com/b/home?lx=B0_lvAtnWygeMrWr4Rfoa",
  "sheets": [
    {
      "id": 4509918431602564,
      "name": "Project Timeline",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=uWicCItTmkbxJwpCfQ5wiwW",
      "createdAt": "2015-06-05T20:05:29Z",
      "modifiedAt": "2015-06-05T20:05:43Z"
    }
  ],
  "reports": [
    {
      "id": 1653067851556740,
      "name": "Weekly report",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=v2DKrX6MH5zx2NEYHxbnlA"
    }
  ],
  "sights": [
    {
      "id": 6327127650920324,
      "name": "Employee Resource Center",
      "accessLevel": "VIEWER",
      "permalink": "https://app.smartsheet.com/b/home?lx=pgjANFWKnpXsljR6Nsts1SnUXphoZCJbZcV5Sw9DPzI",
      "createdAt": "2016-06-16T22:35:53Z",
      "modifiedAt": "2017-08-23T18:58:09Z"
    }
  ]
}

GET /folders/{folderId}

Gets the specified folder (and lists its contents).

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of optional elements to include in the response: ownerInfo - owner's email address and user Id for each sheet sheetVersion - current version number of each sheet, should not be combined with pagination source - the Source object for any sheet that was created from another dashboard, report, sheet, or template, if any
Returns	Folder object, populated according to the include parameter NOTE: If no dashboards, folders, reports, sheets, or templates are present in the folder, the corresponding attribute (for example, folders, sheets) is not present in the response.
Access Scope	READ_SHEETS

List Folders

Gets a list of top-level child folders from the user's Sheets folder (Home), from another folder, or from a workspace.

List Folders (Sheet Level)

Example request: list folders (sheet level)

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

smartsheet.home.listFolders()
  .then(function(folderList) {
    console.log(folderList);
  })
  .catch(function(error) {
    console.log(error);
  })

// Omit pagination parameters
PaginatedResult<Folder> folders = smartsheet.HomeResources.FolderResources.ListFolders(
  null                    // PaginationParameters
);

// Omit pagination parameters
PagedResult<Folder> folders = smartsheet.homeResources().folderResources().listFolders(
  null            // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Home.list_folders(include_all=True)
home_sheets_folders = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Home.list_folders(
  page_size=5,
  page=1)
pages = response.total_pages
folders = response.data

response = smartsheet.folders.list
folders = response[:data]

Example response

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

GET /home/folders

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

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

List Folders (Subfolder)

Example request: list folders (subfolder)

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

// Set options
var options = {
  folderId: 5107651446105988
};

// List folders in another folder
smartsheet.folders.listChildFolders(options)
  .then(function(folderList) {
    console.log(folderList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Folder> folders = smartsheet.FolderResources.ListFolders(
  5107651446105988,           // long folderId
  null                        // PaginationParameters
);

// Omit pagination parameters
PagedResult<Folder> folders = smartsheet.folderResources().listFolders(
  510765144610598L,               // long parentFolderId
  null                             // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Folders.list_folders(
  5107651446105988,       # folder_id
  include_all=True)
folders = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Folders.list_folders(
  5107651446105988,       # folder_id
  page_size=5,
  page=1)
pages = response.total_pages
folders = response.data

response = smartsheet.folders.list_in_folder(
  folder_id: 5107651446105988
)
folders = response[:data]

Example response

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

GET /folders/{folderId}/folders

Gets a list of the top-level child folders within the specified folder.

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

List Folders (Workspace)

Example request: list folders (workspace)

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

// Set options
var options = {
  workspaceId: 1656220827314052
};

// List folders in workspace
smartsheet.workspaces.listWorkspaceFolders(options)
  .then(function(folderList) {
    console.log(folderList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Folder> folders = smartsheet.WorkspaceResources.FolderResources.ListFolders(
  1656220827314052,               // long workspaceId
  null                            // PaginationParameters
);

// Omit pagination parameters
PagedResult<Folder> folders = smartsheet.workspaceResources().folderResources().listFolders(
  1656220827314052L,                   // long workspaceId
  null                                 // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Workspaces.list_folders(
  1656220827314052,       # workspace_id
  include_all=True)
folders = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Workspaces.list_folders(
  1656220827314052,       # workspace_id
  page_size=5,
  page=1)
pages = response.total_pages
folders = response.data

response = smartsheet.folders.list_in_workspace(
  workspace_id: 1656220827314052
)
folders = response[:data]

Example response

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

GET /workspaces/{workspaceId}/folders

Gets a list of the top-level child folders within the specified workspace.

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

Move Folder

Example request: move folder

curl https://api.smartsheet.com/2.0/folders/{folderId}/move \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-d '{ 
  "destinationType": "folder", 
  "destinationId": 7960873114331012 
}' \
-X POST

// Set destination information
var body = {
  destinationType: "folder",
  destinationId: 7960873114331012
};

// Set options
var options = {
  folderId: 4509918431602564,
  body: body
};

// Move folder
smartsheet.folders.moveFolder(options)
  .then(function(folder) {
    console.log(folder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination {
  DestinationId = 7960873114331012,       // long destinationFolderId
  DestinationType = DestinationType.FOLDER,
};

// Move folder
Folder folder = smartsheet.FolderResources.MoveFolder(
  4509918431602564,               // long folderId
  destination
);

// Specify destination
ContainerDestination destination = new ContainerDestination()
  .setDestinationType(DestinationType.FOLDER)
  .setDestinationId(7960873114331012L);

// Move folder
Folder folder = smartsheet.folderResources().moveFolder(
  4509918431602564L,                         // long folderId
  destination
);

folder = smartsheet_client.Folders.move_folder(
  4509918431602564,                           # folder_id to be moved
  smartsheet.models.ContainerDestination({
    'destination_id': 7960873114331012,     # destination folder_id
    'destination_type': 'folder'
  })
)

# Specify destination information
body = {
  destination_type: 'workspace',
  destination_id: 7960873114331012
}

# Move folder
response = smartsheet.folders.move(
  folder_id: 4509918431602564,
  body: body
)

Example response

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

POST /folders/{folderId}/move

Moves the specified folder to another location.

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

Update Folder

Example request: update folder

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

// Set folder name
var folder = {
  "name": "New name for folder"
};

// Set options
var options = {
  id: 7960873114331012, // Id of Folder
  body: folder
};

// Update folder
smartsheet.folders.updateFolder(options)
  .then(function(updatedFolder) {
    console.log(updatedFolder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set folder name
Folder folderSpecification = new Folder
{
  Id = 7960873114331012,
  Name = "New name for folder"
};

// Update folder
Folder updatedFolder = smartsheet.FolderResources.UpdateFolder(folderSpecification);

// Set folder name and id of the folder to be updated
Folder folderSpecification =