Smartsheet API 2.0

Updated 2019-02-06

Overview

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 users and accounts

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 api@smartsheet.com

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 = ss_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
ss_client = smartsheet.Smartsheet('ll352u9jujauoqz4gstvsae05')

# Get current user
user_profile = ss_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.

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

Click the "Account" button in the upper-right corner of the Smartsheet screen, and then click "Personal Settings".
Click the "API Access" tab.
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.

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

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

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.

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.

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:

Postman screen shot

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

Basic sheet with 2 rows and 2 columns

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.

Image of the Sheet Properties window

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
ss_client = smartsheet.Smartsheet(access_token)

# Make sure we don't miss any errors
ss_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%40smartsheet.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");

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

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:

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.
In "Developer Tools", complete your developer profile. This profile is public and anyone can access it to learn about you and your apps.
In "Developer Tools", register your app so Smartsheet can assign a client Id and a client secret to the app.
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.

Open Developer Tools

Log in to Smartsheet with your developer account.
Click the "Account" button in the upper-right corner of your Smartsheet screen, and then click "Developer Tools".
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

Log in to Smartsheet with your developer account.
Click the "Account" button in the upper-right corner of your Smartsheet screen, and then click "Developer Tools".
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 Sights/dashboards structure.
ADMIN_USERS	Add and remove users from your Smartsheet organization; 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 Sights/dashboards.
DELETE_SHEETS	Delete sheets.
DELETE_SIGHTS	Delete Sights/dashboards.
READ_CONTACTS	Retrieve contacts.
READ_SHEETS	Read all sheet data, including attachments, discussions, and cell data.
READ_SIGHTS	Read all Sights/dashboards data.
READ_USERS	Retrieve users and groups for your Smartsheet organization.
SHARE_SHEETS	Share sheets, including sending sheets as attachments.
SHARE_SIGHTS	Share Sights/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:

Simplified graphic showing what data is passed back and forth during 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);
});

// [todo]

// [todo]

# [todo]

# [todo]

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:

Dialog box to allow or deny scopes

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:

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

// 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);
  });

// [todo]

// [todo]

# [todo]

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

Successful Response:

{
    "token": {
        "access_token": "ll352u9jujauoqz4gstvsae05",
        "token_type": "bearer",
        "refresh_token": "e9x352a9mp4151le2505",
        "expires_in": 604799,
        "expires_at": "2017-11-21T23:32:22.180Z"
    }
}

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.
code	Required. Authorization code returned in the previous step.
grant_type	Required. Must be set to "authorization_code".
hash	Required. SHA-256 hash of your app secret concatenated with a pipe and the authorization code. The app_secret is never sent with the request. This is the app_secret you obtained when you registered 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.

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

Refresh an Access Token

Refresh an access token:

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

// 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);
  });

// [todo]

// [todo]

# [todo]

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

Successful Response:

{
    "token": {
        "access_token": "new52u9jujauoqz4gstvsae05",
        "token_type": "bearer",
        "refresh_token": "new352a9mp4151le2505",
        "expires_in": 604799,
        "expires_at": "2017-11-21T23:32:22.180Z"
    }
}

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.
grant_type	Required. Must be set to refresh_token.
hash	Required. SHA-256 hash of your app secret concatenated with a pipe and the refresh token value. To obtain an app_secret, see Register Your App Using Developer Tools.
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 = ss_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,           // long sheetId
  1234567890234568,           // long 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 = ss_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,           // long sheetId
  0123456789012345,           // long 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 = ss_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,           // long 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 = ss_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,           // long sheetId
  0123456789012345,           // long 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 = ss_client.models.Attachment({
  'name': 'Search Engine',
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

# Attach URL to comment
updated_attachment = ss_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,           // long sheetId
  0123456789012345,           // long 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 = ss_client.models.Attachment({
  'name': 'Search Engine',
  'description': 'A popular search engine.'
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

# Attach URL to row
updated_attachment = ss_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,           // long 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 = ss_client.models.Attachment({
  'name': 'Search Engine',
  'description': 'A popular search engine.',
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

# Attach URL to sheet
updated_attachment = ss_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,           // long sheetId
  7169782752536452            // long attachmentId
);

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

ss_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,               // long sheetId
  4583173393803140                // long attachmentId
);

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

attachment = ss_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,           // long sheetId
  null                        // PaginationParameters
);

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

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

# Sample 2: Paginate the list of attachments
response = ss_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,               // long sheetId
  1234567890123456,               // long 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 = ss_client.Attachments.list_discussion_attachments(
  9283173393803140,       # sheet_id 
  1234567890123456,       # discussion_id 
  include_all=True)
attachments = response.data

# Sample 2: Paginate the list
response = ss_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,               // long sheetId
  4293147074291588,               // long 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 = ss_client.Attachments.list_row_attachments(
  2252168947361668,       # sheet_id 
  4293147074291588,       # row_id 
  include_all=True)
attachments = response.data

# Sample 2: Paginate the list
response = ss_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,               // long sheetId
  0123456789123456,               // long 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 = ss_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,               // long sheetId
  0123456789123456                // long attachmentId
);

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

ss_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,               // long sheetId
  5510069950408580,               // long 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 = ss_client.Attachments.list_attachment_versions(
  2252168947361668,       # sheet_id 
  5510069950408580,       # attachment_id
  include_all=True)
versions = response.data

# Sample 2: Paginate the list
response = ss_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);
  });

// Not yet implemented

// 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);
  });

// Not yet implemented

// 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);
  });

// Not yet implemented

// 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);
  });

// Not yet implemented

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

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 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. 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 URL, a sheet, a report, or a Sight.


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 Sight with this Id.
url	string	When the hyperlink is a URL link, this property contains the URL value. When the hyperlink is a sheet/report/Sight link (that is, sheetId, reportId, or sightId is non-null), this property contains the permalink to the sheet, report, or Sight.

ObjectValue Object

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, 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}}]}}]}]'

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,               // long sheetId
  0123456789012345,               // long rowId
  4567890123456789,               // long 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,               // long sheetId
  0123456789012345,               // long rowId
  4567890123456789,               // long 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 = ss_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 = ss_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.

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 details, such as email addresses. 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 report, sheet, or Sight (aka dashboard) that you are querying, otherwise the column type is TEXT_NUMBER.	Yes: same as value; to see actual email addresses, 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 details, use both a level query parameter and an include=objectValue query to see email addresses rather than display names.

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.

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 sheet, report, or Sight link, the cell's value is set to the sheet, report, or Sight 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"
ss_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"

// [todo]

long sheetId = 1639534409607044;
long rowId = 3344087179913092;
long 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 = ss_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 = ss_client.models.ImageUrl( { "imageId": image_id } )
response = ss_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 = ss_client.models.ImageUrl(
  {
    "imageId": 'jpbGklqdfZuL4Jw-kZhdZA',
    "height": 256,
    "width": 256
  }
)

response = ss_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": 0,
  "index": 0,
  "symbol": "STAR",
  "title": "Favorite",
  "type": "CHECKBOX",
  "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 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
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.
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 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	A zero-based integer indicating whether the column allows multi-contact data. A value of 0 indicates the data will be stored as text and the column type will be TEXT_NUMBER, a value of 1 for sheets and reports or a value of 2 for Sights (aka dashboards) indicates the data will be stored as contacts and the column type will be MULTI_CONTACT_LIST. If not specified, the default value is 0 for sheets and reports or 1 for Sights (aka dashboards).
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 Picklist Column 1", "type": "PICKLIST", "options": ["First", "Second", "Third"], "index": 4} , {"title":"New Date Column", "type":"DATE", "validation":"true", "index":4},]'

// Specify new columns
var column = [
  {
    "title": "New Picklist Column 1",
    "type": "PICKLIST",
    "options": [
      "First",
      "Second",
      "Third"
    ],
    "index": 4
  },
  {
    "title": "New Date Column",
    "type": "DATE",
    "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 = "New Picklist Column 1",
  Index = 4,
  Type = ColumnType.PICKLIST,
  Options = new string[] { "First", "Second", "Third" }
};

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

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

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

Column column2 = new Column()
  .setTitle("New Date Column")
  .setType(ColumnType.DATE)
  .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 = ss_client.models.Column({
  'title': 'New Picklist Column 1',
  'type': 'PICKLIST',
  'options': [
    'First',
    'Second',
    'Third'
  ],
  'index': 4
})

column2 = ss_client.models.Column({
  'title': 'New Date Column',
  'type': 'DATE',
  'validation': 'true',
  'index': 4
})

# Add columns to the sheet
new_columns = ss_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',
  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",
      "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 autoNumberFormat (optional) index (zero-based, 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,               // long sheetId
  0123456789012345                // long columnId
);

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

ss_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,               // long sheetId
  7960873114331012,               // long columnId
  null                            // IEnumerable<ColumnInclusion> includes
);

// Sample 2: Specify 'include' parameter with value of "FILTERS"
Column column = smartsheet.SheetResources.ColumnResources.GetColumn(
  9283173393803140,               // long sheetId
  7960873114331012,               // long 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 = ss_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
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,               // long sheetId
  null,                           // IEnumerable<ColumnInclusion> include
  null                            // PaginationParameters
);

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

response = ss_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.
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":"First Column","index":0, "type" : "PICKLIST", "options" :["One","Two"]}'

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

// Set options
var options = {
  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 = ss_client.models.Column({
  'title': 'First Column',
  'type': 'PICKLIST',
  'options': ["One", "Two"],
  'index': 0
})

# Update column
response = ss_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 title -- required when creating a column, optional after that autoNumberFormat (optional) contactOptions (optional) -- must have set column type to CONTACT_LIST format (optional) hidden (optional) locked (optional) options (optional) symbol (optional) systemColumnType (optional) type (optional) validation (optional) width (optional)
Returns	Result object containing the Column object that was modified
Access Scope	ADMIN_SHEETS

Column Types

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

Column Type	Column.type Value	Notes
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 report, sheet, or Sight (aka dashboard) 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.
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 simply 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,               // long sheetId
  3962273862576004,               // long 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 = ss_client.Discussions.add_comment_to_discussion(
  2252168947361668,       # sheet_id
  3962273862576004,       # discussion_id
  ss_client.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,                   // long sheetId
  3962273862576004,                   // long 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 = ss_client.models.Comment({
  'text': 'This is a new comment.'
})

# Add comment (with attachment) to discussion
response = ss_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,          // long sheetId
  commentSpecification
);

[todo]

comment = ss_client.Discussions.update_comment(
  3285357287499652,       # sheet_id
  7144101943502724,       # comment_id
  ss_client.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,           // long sheetId
  4952999001909124            // long commentId
);

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

ss_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,               // long sheetId
  48569348493401200               // long commentId
);

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

comment = ss_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

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 = ss_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
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 = ss_client.Contacts.list_contacts(include_all=True)
contacts = response.data

# Sample 2: Paginate the list (100 contacts per page)
response = ss_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));
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

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));
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

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));
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

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

Dashboards and Sights(TM) are two terms for one thing. Dashboard information is managed using the Sights endpoints and properties. For more information, see the Sights section.

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,               // long sheetId
  0123456789012345,               // long 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,       // long sheetId
  0123456789012345L,       // long rowId
  discussionSpecification
);

response = ss_client.Discussions.create_discussion_on_row(
  9283173393803140,           # sheet_id
  0123456789012345,           # row_id
  ss_client.models.Discussion({
    'comment': ss_client.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,                   // long sheetId
  0123456789012345,                   // long 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 = ss_client.Discussions.create_discussion_on_row_with_attachment(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  ss_client.models.Discussion({
    'comment': ss_client.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,                   // long 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 = ss_client.Discussions.create_discussion_on_sheet(
  9283173393803140,           # sheet_id
  ss_client.models.Discussion({
    'comment': ss_client.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,                   // long 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 = ss_client.Discussions.create_discussion_on_sheet_with_attachment(
  9283173393803140,           # sheet_id
  ss_client.models.Discussion({
    'comment': ss_client.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,               // long sheetId
  0123456789012345                // long discussionId
);

smartsheet.sheetResources().discussionResources().deleteDiscussion(
  9283173393803140L,       // long sheetId
  0123456789012345L        // long discussionId
);

ss_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,               // long 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,               // long 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 = ss_client.Discussions.get_all_discussions(
  9283173393803140,       # sheet_id
  include_all=True)
discussions = response.data

# Sample 2: Paginate the list
response = ss_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,               // long sheetId
  0123456789012345                // long discussionId
);

Discussion discussion = smartsheet.sheetResources().discussionResources().getDiscussion(
  9283173393803140L,       // long sheetId
  0123456789012345L        // long discussionId
);

discussion = ss_client.Discussions.get_discussion(
  9283173393803140,       # sheet_id
  0123456789012345)       # discussion_id

# discussion is an instance of ss_client.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,                   // long sheetId
  4293147074291588,                   // long 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,                   // long sheetId
  4293147074291588,                   // long 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 = ss_client.Discussions.get_row_discussions(
  2252168947361668,               # sheet_id
  4293147074291588,               # row_id
  include_all=True)
discussions = response.data

# Sample 2: Paginate the list
response = ss_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

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" folders, reports, sheets, Sights, 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 = ss_client.Favorites.add_favorites([
  ss_client.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 = ss_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 }   // long folderId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.FOLDER,
  new HashSet(Arrays.asList(2252168947361668L))      // long folderId
);

ss_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 }       // long reportId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.REPORT,
  new HashSet(Arrays.asList(2252168947361668L))         // long reportId
);

ss_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 }   // long sheetId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.SHEET,
  new HashSet(Arrays.asList(2252168947361668L))         // long sheetId
);

ss_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 Sight

Example request: remove favorite sight

curl https://api.smartsheet.com/2.0/favorites/sight/{sightId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  objectId: 6327127650920324
};

// Remove Sight from list of favorites
smartsheet.favorites.removeSightFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// [todo]

ss_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 Sight 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 }     // long templateId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.TEMPLATE,
  new HashSet(Arrays.asList(2252168947361668L))         // long templateId
);

ss_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 }   // long workspaceId
);

smartsheet.favoriteResources().removeFavorites(
  FavoriteType.WORKSPACE,
  new HashSet(Arrays.asList(2252168947361668L))       // long workspaceId
);

ss_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
);

ss_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
);

ss_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
);

ss_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 Sights

Example request: remove multiple favorite Sights

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 Sights from list of favorites
smartsheet.favorites.removeSightsFromFavorites(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// [todo]

ss_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 Sights 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
);

ss_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
);

ss_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	Sight[]	Array of Sight 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 = ss_client.Folders.copy_folder(
  2252168947361668,                           # folder_id
  ss_client.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.
	omit (optional) -- when specified with a value of sheetHyperlinks, excludes this category from the response
	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, reports, sheet hyperlinks, and Sights 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 Sights 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 = ss_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 = ss_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 = ss_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
);

ss_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 = ss_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 sheet or template
Returns	Folder object, populated according to the include parameter NOTE: If no folders, reports, sheets, Sights, 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 = ss_client.Home.list_folders(include_all=True)
home_sheets_folders = response.data

# Sample 2: Paginate the list
response = ss_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 = ss_client.Folders.list_folders(
  5107651446105988,       # folder_id
  include_all=True)
folders = response.data

# Sample 2: Paginate the list
response = ss_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 = ss_client.Workspaces.list_folders(
  1656220827314052,       # workspace_id
  include_all=True)
folders = response.data

# Sample 2: Paginate the list
response = ss_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 = ss_client.Folders.move_folder(
  4509918431602564,                           # folder_id to be moved
  ss_client.models.Destination({
    '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 = new Folder(7960873114331012L);
folderSpecification.setName("New name for folder");

// Update folder
Folder updatedFolder = smartsheet.folderResources().updateFolder(folderSpecification);

updated_folder = ss_client.Folders.update_folder(
  7960873114331012,       # folder_id
  'New name for folder')

# Set options
body = {
  name: 'New name for folder'
}

# Update folder
response = smartsheet.folders.update(
  folder_id: 7960873114331012,
  body: body
)

Example response

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

PUT /folders/{folderId}

Updates the folder specified in the URL.


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

Groups

A group is a collection of group members.

Objects

Group Object

Example: Group object

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


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

Create Group

Example request: create group

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

// Specify group
var group = {
  "name": "API-created Group",
  "description": "Group created via API",
  "members": [
    {
      "email": "john.doe@smartsheet.com"
    }
  ]
};

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

// Create group
smartsheet.groups.createGroup(options)
  .then(function(newGroup) {
    console.log(newGroup);
  })
  .catch(function(error) {
    console.log(error);
  });

// Create group member
GroupMember memberSpecification = new GroupMember { Email = "john.doe@smartsheet.com" };

// Add member to group
Group groupSpecification = new Group
{
  Name = "API-created Group",
  Description = "Group created via API",
  Members = new GroupMember[] { memberSpecification }
};

// Create group
Group newGroup = smartsheet.GroupResources.CreateGroup(groupSpecification);

// Create group member
GroupMember memberSpecification = new GroupMember();
memberSpecification.setEmail("john.doe@smartsheet.com");

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

// Create group
Group newGroup = smartsheet.groupResources().createGroup(groupSpecification);

new_group = ss_client.Groups.create_group(
  ss_client.models.Group({
    'name': 'API-created Group',
    'description': 'Group created via API',
    'members': ss_client.models.GroupMember({
      'email': 'john.doe@smartsheet.com'
    })
  })
)

# List members of group
body = {
  name: 'API-created Group',
  description: 'Group created via API',
  members: [
    {
      email: 'john.doe@smartsheet.com'
    }
  ]
}

# Create group
new_group = smartsheet.groups.create(
  body: body
)

Example response

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

POST /groups

Creates a new group.


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

Delete Group

Example request: delete group

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

// Set options
var options = {
  id: 6932724448552836 // Id of Group
};

// Delete group
smartsheet.groups.deleteGroup(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.GroupResources.DeleteGroup(
  6932724448552836            // long groupId
);

smartsheet.groupResources().deleteGroup(
  6932724448552836L        // long groupId
);

ss_client.Groups.delete_group(
    6932724448552836)       # group_id

smartsheet.groups.delete(
  group_id: 4583173393803140
)

Example response

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

DELETE /groups/{groupId}

Deletes the group specified in the URL.


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_USERS

Get Group

Example request: get group

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

// Set options
var options = {
  id: 6932724448552836 // Id of Group
};

// Get group
smartsheet.groups.getGroup(options)
  .then(function(group) {
    console.log(group);
  })
  .catch(function(error) {
    console.log(error);
  });

Group group = smartsheet.GroupResources.GetGroup(
  6932724448552836            // long groupId
);

Group group = smartsheet.groupResources().getGroup(
  6932724448552836L        // long groupId
);

group = ss_client.Groups.get_group(
  6932724448552836)       # group_id
# group is an instance of ss_client.models.Group

group = smartsheet.groups.get(
  group_id: 6932724448552836
)

Example response

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

GET /groups/{groupId}

Gets the group specified in the URL.


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Group object that includes the list of GroupMember objects
Access Scope	READ_USERS

List Org Groups

Example request: list org groups

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

smartsheet.groups.listGroups()
  .then(function(groupList) {
    console.log(groupList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Group> groups = smartsheet.GroupResources.ListGroups(
  null                    // PaginationParameters
);

// Omit pagination parameters
PagedResult<Group> groups = smartsheet.groupResources().listGroups(
  null        // PaginationParameters
);

# Sample 1: List all
response = ss_client.Groups.list_groups(include_all=True)
groups = response.data

# Sample 2: Paginate the list
response = ss_client.Groups.list_groups(
  page_size=10,
  page=1)
pages = response.total_pages
groups = response.data

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

Example response

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

GET /groups

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


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 Group objects
Access Scope	READ_USERS

Update Group

Example request: update group

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

// Specify the name and description of the group
var group = {
  "name": "Renamed Group",
  "description": "Some new description"
};

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

// Update group
smartsheet.groups.updateGroup(options)
  .then(function(updatedGroup) {
    console.log(updatedGroup);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify the name and description of the group
Group groupSpecification = new Group
{
  Id = 2331373580117892,
  Name = "Renamed Group",
  Description = "Some new description"
};

// Update group
Group updatedGroup = smartsheet.GroupResources.UpdateGroup(groupSpecification);

// Specify the name and description of the group
Group groupSpecification = new Group(2331373580117892L);
groupSpecification.setDescription("Some new description")
  .setName("Renamed Group");

// Update group
Group updatedGroup = smartsheet.groupResources().updateGroup(groupSpecification);

updated_group = ss_client.Groups.update_group(
  2331373580117892,       # group_id
  ss_client.models.Group({
    'name': 'Renamed Group',
    'description': 'Some new description'
  })
)

# Specify the name and description of the group
body = {
  name: 'Renamed Group',
  description: 'Some new description',
  owner_id: 4583173393803140
}

# Update group
updated_group = smartsheet.groups.update(
  group_id: 2331373580117892,
  body: body
)

Example response

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

PUT /groups/{groupId}

Updates the Group specified in the URL.


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

Group Members

A group member is a user that belongs to a group.

Objects

Example: GroupMember object

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

GroupMember Object


id	number	Group member's user Id
email	string	Group member's email address
firstName	string	Group member's first name
lastName	string	Group member's last name
name	string	Group member's full name

Add Group Members

Example request: add group members

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

// Specify group members
var members = [{ "email": "jane.doe@smartsheet.com" }];

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

// Add members to group
smartsheet.groups.addGroupMembers(options)
  .then(function(newMembers) {
    console.log(newMembers);
  })
  .catch(function(error) {
    console.log(error);
  });

// Create group member
GroupMember memberSpecification = new GroupMember { Email = "jane.doe@smartsheet.com" };

// Add members to group
IList<GroupMember> newMembers = smartsheet.GroupResources.AddGroupMembers(
  7917992160847748,           // long groupId
  new GroupMember[] { memberSpecification }
);

// Create group member
GroupMember memberSpecification = new GroupMember();
memberSpecification.setEmail("jane.doe@smartsheet.com");

// Add members to group
List<GroupMember> newMembers = smartsheet.groupResources().memberResources().addGroupMembers(
  7917992160847748L,       // long groupId
  Arrays.asList(memberSpecification)
);

new_members = ss_client.Groups.add_members(
  7917992160847748,       # group_id
  [ss_client.models.GroupMember({'email': 'jane.doe@smartsheet.com'})]
)

body = {
  email: 'jane.doe@smartsheet.com'
}

new_members = smartsheet.groups.add_members(
  group_id: 7917992160847748,
  body: body
)

Example response

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

POST /groups/{groupId}/members

Adds one or more members to a group.

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


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	A single GroupMember object or an array of GroupMember objects, limited to the following attribute: email
Returns	Result object containing the members added to the group -- either a single GroupMember or array of GroupMember objects, corresponding to what was specified in the request.
Errors	If an error occurs because the request specified one or more alternate email addresses, please retry using the primary email address.
Access Scope	ADMIN_USERS

Remove Group Member

Example request: remove group member

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

// Set options
var options = {
  groupId: 7917992160847748,
  userId: 1539725208119172
};

// Remove member from group
smartsheet.groups.removeGroupMember(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.GroupResources.RemoveGroupMember(
  7917992160847748,           // long groupId
  1539725208119172            // long userId
);

smartsheet.groupResources().memberResources().deleteGroupMember(
  7917992160847748L,       // long groupId
  1539725208119172L)       // long userId
);

ss_client.Groups.remove_member(
  7917992160847748,       # group_id
  1539725208119172)       # group_member_id

smartsheet.groups.remove_member(
  group_id: 4583173393803140,
  user_id: 48569348493401200
)

Example response

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

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

Removes a member from a group.


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_USERS

Home

In the Smartsheet UI, the "Home" tab shows all objects a user has access to, including folders, reports, sheets, Sights, templates, and workspaces.

Objects

Home Object

Example: Home object

{
  "folders": [],
  "sheets": [],
  "reports": [],
  "templates": [],
  "workspaces": [],
  "sights": []
}


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

List Contents

Example request: list contents

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

smartsheet.home.listContents()
  .then(function(contents) {
    console.log(contents);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include' parameters
Home home = smartsheet.HomeResources.GetHome(
  null                // IEnumerable<HomeInclusion> includes
);

// Sample 2: Specify 'include' parameter with value of "SOURCE"
Home home = smartsheet.HomeResources.GetHome(
  new HomeInclusion[] { HomeInclusion.SOURCE }
);

// Sample 1: Omit 'include' parameter
Home home = smartsheet.homeResources().getHome(
  null            // EnumSet<SourceInclusion> includes
);

// Sample 2: Specify 'include' parameter with value of "SOURCE"
Home home = smartsheet.homeResources().getHome(EnumSet.of(SourceInclusion.SOURCE)));

contents = ss_client.Home.list_all_contents(include='source')

contents = smartsheet.home.list

Example response

{
  "folders": [
    {
      "id": 5709073300645764,
      "name": "folder 1",
      "permalink": "https://app.smartsheet.com/b/home?lx=Dsje3YKtpyZScrCX6Z1"
    }
  ],
  "sheets": [
    {
      "id": 4583173393803140,
      "name": "sheet 1",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=Dsje3YKtpyZScrCX6Za", 
      "createdAt": "2015-06-05T20:05:29Z",
      "modifiedAt": "2015-06-05T20:05:43Z"
    },
    {
      "id": 2331373580117892,
      "name": "Copy of sheet 1",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=Dsje3YKtpyZScrCX6Zb",
      "createdAt": "2015-06-05T20:05:29Z",
      "modifiedAt": "2015-06-05T20:05:43Z",
      "source": {
        "id": 4583173393803140,
        "type": "sheet"
        }
      }
  ],
  "reports": [],
  "templates": [],
  "workspaces": [],
  "sights": []
}

GET /home

Gets a nested list of all Home objects, including folders, reports, sheets, Sights, templates, and workspaces, as shown on the "Home" tab.


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 sheet that was created from another sheet or template
	exclude (optional) -- a comma-separated list of optional elements to not include in the response. permalinks - excludes the permalink from each data object
Returns	Home object, populated according to the include parameter
Access Scope	READ_SHEETS

Home Folders

For details about working with folders in the user's Sheets folder (that is, at the Home level), see Folders.

Home Sheets

For details about working with sheets in the user's Sheets folder (that is, at the Home level), see Sheets.

Import

Import CSV or XLSX data into a new sheet.

Import Sheet from CSV / XLSX

Example request: Import sheet

curl  https://api.smartsheet.com/2.0/sheets/import?sheetName=MarketingProgressReport&headerRowIndex=0&primaryColumnIndex=0 \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Disposition: attachment" \
-H "Content-Type: text/csv" \
-X POST \
--data-binary @ProgressReport.csv

// Sample 1: Import sheet from CSV
// Set options
var options = {
  queryParameters: {
      sheetName: 'MarketingProgressReport'
  },
  path: "D:/ProgressReport.csv"
};

// Import CSV as sheet
smartsheet.sheets.importCsvSheet(options)
  .then(function(attachment) {
      console.log(attachment);
  })
  .catch(function(error) {
      console.log(error);
  });

// Sample 2: Import sheet from XLSX
// Set options
var options = {
  queryParameters: {
    sheetName: 'MarketingProgressReport'
  },
  path: "D:/ProgressReport.xlsx"
};

// Import XLSX as sheet
smartsheet.sheets.importXlsxSheet(options)
  .then(function(attachment) {
    console.log(attachment);
  })
  .catch(function(error) {
    console.log(error);
  });

Sheet sheet = smartsheet.SheetResources.ImportXlsSheet(
  "D:/ProgressReport.xlsx",
  null,         // sheetName defaults to file name unless specified
  0,            // headerRowIndex
  null          // primaryColumnIndex
);

Sheet sheet = smartsheet.sheetResources().importXlsx(
  "D:/ProgressReport.xlsx",
  "MarketingProgressReport",
  0,      // headerRowIndex
  0       // primaryColumnIndex
);

imported_sheet = ss_client.Sheets.import_xlsx_sheet(
  'D:/ProgressReport.xlsx',
  'MarketingProgressReport',  # sheet_name
  header_row_index=0
)

# Sample 1: Import from file
smartsheet.sheets.import_from_file(
  file: ProgressReport.csv,
  file_type: :csv,
  file_length: ProgressReport.size,
  params: {sheetName: 'MarketingProgressReport', headerRowIndex: 0, primaryColumnIndex: 0})

# Sample 2: Import from file path
smartsheet.sheets.import_from_file_path(
  path: 'D:\ProgressReport.csv',
  file_type: :csv,
  params: {sheetName: 'MarketingProgressReport', headerRowIndex: 0, primaryColumnIndex: 0})

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
      "id": 9271131230488452,
      "name": "MarketingProgressReport",
      "type": "sheet",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=eGUIdBiqQXj7yxLaCINt3g"
  }
}

POST /sheets/import

Imports CSV or XLSX data into a new sheet in the top-level "sheets" folder.


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
	Content-Disposition: attachment
	One of the following: For CSV files, use: Content-Type: text/csv For XLSX files, use: Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Parameters	sheetName (required) -- desired name of the sheet.
	headerRowIndex (optional) -- a zero-based integer indicating the row number to use for column names. Rows before this are omitted. If not specified, the default values are Column1, Column2, etc.
	primaryColumnIndex (optional) -- a zero-based integer indicating the column to designate as primary. If not specified, the default value is 0.
Request Body	Binary content for the file
Returns	Result object
Access Scope	CREATE_SHEETS

Import Sheet into Folder

Example request: Import sheet into folder

curl  https://api.smartsheet.com/2.0/folders/{folderId}/sheets/import?sheetName=MarketingProgressReport&headerRowIndex=0&primaryColumnIndex=0 \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Disposition: attachment" \
-H "Content-Type: text/csv" \
-X POST \
--data-binary @ProgressReport.csv

// Sample 1: Import CSV into folder
// Set options
var options = {
  folderId: 8999900887877508, 
  queryParameters: {
    sheetName: 'MarketingProgressReport'
  },
  path: "D:/ProgressReport.csv"
};

// Import CSV as sheet into folder
smartsheet.sheets.importCsvSheetIntoFolder(options)
  .then(function(attachment) {
    console.log(attachment);
  })
  .catch(function(error) {
    console.log(error);
  });

//Sample 2: Import XLSX into folder
// Set options
var options = {
  folderId: 8999900887877508, 
  queryParameters: {
    sheetName: 'MarketingProgressReport'
  },
  path: "D:/ProgressReport.xlsx"
};

// Import XLSX as sheet into Folder
smartsheet.sheets.importXlsxSheetIntoFolder(options)
  .then(function(attachment) {
    console.log(attachment);
  })
  .catch(function(error) {
    console.log(error);
  });

Sheet sheet = smartsheet.FolderResources.SheetResources.ImportXlsSheet(
  8999900887877508,       // folderId
  "D:/ProgressReport.xlsx",
  null,                   // sheetName defaults to file name unless specified
  0,                      // headerRowIndex
  null                    // primaryColumnIndex
);

Sheet sheet = smartsheet.sheetResources().importXlsxInFolder(
  8999900887877508L,           // long folderId
  "D:/ProgressReport.xlsx",
  "MarketingProgressReport",
  0,                          // headerRowIndex
  0                           // primaryColumnIndex
);

imported_sheet = ss_client.Folders.import_xlsx_sheet(
  8999900887877508,           # folder_id
  'D:/ProgressReport.xlsx',
  'MarketingProgressReport',  # sheet_name
  header_row_index=0
)

# Sample 1: Import from file into folder
smartsheet.sheets.import_from_file_into_folder(
  folder_id: 8999900887877508,
  file: sample_csv,
  file_type: :csv,
  file_length: sample_csv.size,
  params: {sheetName: 'MarketingProgressReport', headerRowIndex: 0, primaryColumnIndex: 0})

# Sample 2: Import from file path into folder
smartsheet.sheets.import_from_file_path_into_folder(
  folder_id: 89999300887877508,
  path: 'D:\sample.csv',
  file_type: :csv,
  params: {sheetName: 'MarketingProgressReport', headerRowIndex: 0, primaryColumnIndex: 0})

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
      "id": 9271131230488452,
      "name": "MarketingProgressReport",
      "type": "sheet",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=eGUIdBiqQXj7yxLaCINt3g"
  }
}

POST /folders/{folderId}/sheets/import

Imports CSV or XLSX data into a new sheet in the specified folder.


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
	Content-Disposition: attachment
	One of the following: For CSV files, use: Content-Type: text/csv For XLSX files, use: Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Parameters	sheetName (required) -- desired name of the sheet.
	headerRowIndex (optional) -- a zero-based integer indicating the row number to use for column names. Rows before this are omitted. If not specified, the default values are Column1, Column2, etc.
	primaryColumnIndex (optional) -- a zero-based integer indicating the column to designate as primary. If not specified, the default value is 0.
Request Body	Binary content for the file
Returns	Result object
Access Scope	CREATE_SHEETS

Import Sheet into Workspace

Example request: Import sheet into workspace

curl  https://api.smartsheet.com/2.0/workspaces/{workspaceId}/sheets/import?sheetName=MarketingProgressReport&headerRowIndex=0&primaryColumnIndex=0 \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Disposition: attachment" \
-H "Content-Type: text/csv" \
-X POST \
--data-binary @ProgressReport.csv

// Sample 1: Import CSV into workspace
// Set options
var options = {
  workspaceId: 4124946017347460,
  queryParameters: {
    sheetName: 'MarketingProgressReport'
  },
  path: "D:/ProgressReport.csv"
};

// Import CSV as sheet into workspace
smartsheet.sheets.importCsvSheetIntoWorkspace(options)
  .then(function(attachment) {
    console.log(attachment);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 2: Import XLSX into workspace
// Set options
var options = {
  workspaceId: 4124946017347460,
  queryParameters: {
    sheetName: 'MarketingProgressReport'
  },
  path: "D:/ProgressReport.xlsx"
};

// Import XLSX as sheet into workspace
smartsheet.sheets.importXlsxSheetIntoWorkspace(options)
  .then(function(attachment) {
    console.log(attachment);
  })
  .catch(function(error) {
    console.log(error);
  });

Sheet sheet = smartsheet.WorkspaceResources.SheetResources.ImportXlsSheet(
  4124946017347460,       // workspaceId
  "D:/ProgressReport.xlsx",
  null,                   // sheetName defaults to file name unless specified
  0,                      // headerRowIndex
  null                    // primaryColumnIndex
);

Sheet sheet = smartsheet.sheetResources().importXlsxInWorkspace(
  4124946017347460L,           // long workspaceId
  "D:/ProgressReport.xlsx",
  "MarketingProgressReport",
  0,                          // headerRowIndex
  0                           // primaryColumnIndex
);

imported_sheet = ss_client.Workspaces.import_xlsx_sheet(
  4124946017347460,           # workspace_id
  'D:/ProgressReport.xlsx',
  'MarketingProgressReport',  # sheet_name
  header_row_index=0
)

# Sample 1: Import from file into workspace
smartsheet.sheets.import_from_file_into_workspace(
  workspace_id: 4124946017347460,
  file: sample_csv,
  file_type: :csv,
  file_length: sample_csv.size,
  params: {sheetName: 'MarketingProgressReport', headerRowIndex: 0, primaryColumnIndex: 0})

# Sample 2: Import from file path into workspace
smartsheet.sheets.import_from_file_path_into_workspace(
  workspace_id: 4124946017347460,
  path: 'D:\sample.csv',
  file_type: :csv,
  params: {sheetName: 'MarketingProgressReport', headerRowIndex: 0, primaryColumnIndex: 0})

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
      "id": 9271131230488452,
      "name": "MarketingProgressReport",
      "type": "sheet",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=eGUIdBiqQXj7yxLaCINt3g"
  }
}

POST /workspaces/{workspaceId}/sheets/import

Imports CSV or XLSX data into a new sheet in the specified workspace.


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
	Content-Disposition: attachment
	One of the following: For CSV files, use: Content-Type: text/csv For XLSX files, use: Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Parameters	sheetName (required) -- desired name of the sheet.
	headerRowIndex (optional) -- a zero-based integer indicating the row number to use for column names. Rows before this are omitted. If not specified, the default values are Column1, Column2, etc.
	primaryColumnIndex (optional) -- a zero-based integer indicating the column to designate as primary. If not specified, the default value is 0.
Request Body	Binary content for the file
Returns	Result object
Access Scope	CREATE_SHEETS

Reports

A report is a filtered view of the data from one or more sheets. Like a sheet, a report is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

Objects

Report Object

Example: Report object

{
  "id": 4583173393803140,
  "name": "My Report",
  "totalRowCount": 4,
  "accessLevel": "OWNER",
  "permalink": "https://app.smartsheet.com/b/home?lx=pWNSDH9itjBXxBzFmyf-5w",
  "createdAt": "2012-07-24T18:22:29-07:00",
  "modifiedAt": "2012-07-24T18:30:52-07:00",
  "columns": [],
  "rows": []
}

Extends the Sheet object, adding the following:


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

ReportCell Object

Extends the Cell object, adding the following:


virtualColumnId	number	The virtual Id of the cell's column. This property refers to the cell's parent column in the report, while the columnId property refers to the cell's parent column in its originating source sheet.

ReportColumn Object

Extends the Column object, adding the following:


virtualId	number	The virtual Id of this report column
sheetNameColumn	Boolean	Returned only for the special "Sheet Name" report column (value = true)

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

ReportRow Object

Extends the Row object, adding the following:


sheetId	number	The Id of the sheet from which the row originates

ReportPublish Object


readOnlyFullAccessibleBy	string	Indicates who can access the 'Read-Only Full' view of the published report: If ALL, it is available to anyone who has the link. If ORG, it is available only to members of the report owner's Smartsheet organization. Only returned in a response if readOnlyFullEnabled = true.
readOnlyFullDefaultView	string	Indicates which view the user has set for a read-only, default view of the published report. Must be one of the following values: CALENDAR, CARD, or GRID.
readOnlyFullEnabled	Boolean	(Required) If true, a rich version of the report is published with the ability to download row attachments and discussions.
readOnlyFullShowToolbar	Boolean	DEPRECATED Indicates whether the left nav toolbar is displayed. The default, or true, is to display the toolbar. If false, hides the toolbar.
readOnlyFullUrl	string	URL for 'Read-Only Full' view of the published report Only returned in a response if readOnlyFullEnabled = true.

Get Report

Example request: get report

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

// Set options
var options = {
  id: 4583173393803140 // Id of Report
};

// Get report
smartsheet.reports.getReport(options)
  .then(function(report) {
    console.log(report);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include', 'pageSize', and 'page' parameters
Report report = smartsheet.ReportResources.GetReport(
  4583173393803140,           // long reportId
  null,                       // IEnumerable<ReportInclusion> include
  null,                       // int pageSize
  null                        // int page
);

// Sample 2: Specify 'include' parameter with value of "ATTACHMENTS" and "DISCUSSIONS", 'pageSize' parameter with value of "500", and 'page' of value "2"
Report report = smartsheet.ReportResources.GetReport(
  4583173393803140,           // long reportId
  new ReportInclusion[] {
    ReportInclusion.ATTACHMENTS,
    ReportInclusion.DISCUSSIONS
  },
  500,                        // int pageSize
  2                           // int page
);

// Sample 1: Omit 'include', 'pageSize', and 'page' parameters
Report report = smartsheet.reportResources().getReport(
  4583173393803140L,      // long reportId
  null,                   // EnumSet<ReportInclusion> includes
  null,                   // int pageSize
  null                    // int page
);

// Sample 2: Specify 'include' parameter with value of "ATTACHMENTS" and "DISCUSSIONS", 'pageSize' parameter with value of "500", and 'page' of value "2"
Report report = smartsheet.reportResources().getReport(
  4583173393803140L,      // long reportId
  EnumSet.of(
    ReportInclusion.ATTACHMENTS,
    ReportInclusion.DISCUSSIONS),
  500,                    // int pageSize
  2                       // int page
);

report = ss_client.Reports.get_report(
  4583173393803140)       # report_id

report = smartsheet.reports.get(
  report_id: 4583173393803140
)

Example response

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

  ]
}

GET /reports/{reportId}

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


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of optional elements to include in the response: attachments discussions format -- see Formatting objectValue -- when used in combination with a level query parameter, includes the email addresses for multi-contact data sourceSheets
	exclude (optional) -- a comma-separated list of optional elements to not include in the response. linkInFromCellDetails: excludes the following attributes from the cell.linkInFromCell object: columnId rowId status linksOutToCellsDetails: excludes the following attributes from the cell.linksOutToCells array elements: columnId rowId status
	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).
	pageSize (optional): Number of rows per page. If not specified, the default value is 100. If you need larger sets of data from your report, this operation can return a maximum of 10,000 rows per request (report limit is 50,000 rows).
	page (optional): Which page number (1-based) to return. If not specified, the default value is 1. If a page number is specified that is greater than the number of total pages, the last page is returned.
Returns	Report object, populated according to the specified parameters
Access Scope	READ_SHEETS

Get Report as Excel / CSV

Example request: get report as Excel

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

var fs = require("fs")

// Set options
var options = {
  id: 3882962191181700 // Id of Report
};

// Get sheet
smartsheet.reports.getReportAsExcel(options)
  .then(function(fileContents) {
    // Write report to file
    fs.writeFile('output.xlsx', fileContents, 'binary', (err) => {
      if (err) throw err;
      console.log('The report has been saved!');
    });
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.ReportResources.GetReportAsExcel(
  3882962191181700,               // long reportId
  outputStream                    // BinaryWriter
);

smartsheet.reportResources().getReportAsExcel(
    3882962191181700L,       // long reportId
    outputStream
);

# Sample 1: Download file with filename suggested by API
ss_client.Reports.get_report_as_excel(
  3882962191181700,       # report_id
  download_folder_path
)

# Sample 2: Specify custom filename for the downloaded file
ss_client.Reports.get_report_as_excel(
  3882962191181700,       # report_id
  download_folder_path,
  'MyFileName.xslx'
)

file_contents = smartsheet.reports.get_as_excel(
  report_id: 4583173393803140
)

File.open('output.xlsx', 'w') {|f| f.write(file_contents)}

Example response

# See local file named "output.xlsx"

// See local file named "output.xlsx"

// Contents of Excel file is written to "outputStream"

// Contents of Excel file is written to "outputStream"

# download folder contains the downloaded Excel file

# See local file named "output.xlsx"

Example request: get report as CSV

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

var fs = require("fs")

// Set options
var options = {
  id: 3882962191181700 // Id of Report
};

// Get sheet
smartsheet.reports.getReportAsCSV(options)
  .then(function(fileContents) {
    // Write report to file
    fs.writeFile('output.csv', fileContents, (err) => {
      if (err) throw err;
      console.log('The report has been saved!');
    });
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.ReportResources.GetReportAsCSV(
  3882962191181700,           // long reportId
  outputStream                // BinaryWriter
);

smartsheet.reportResources().getReportAsCsv(
  3882962191181700L,       // long reportId
  outputStream
);

# Sample 1: Download file with filename suggested by API
ss_client.Reports.get_report_as_csv(
  3882962191181700,       # report_id
  download_folder_path
)

# Sample 2: Specify custom filename for the downloaded file
ss_client.Reports.get_report_as_csv(
  3882962191181700,       # report_id
  download_folder_path,
  'CallMeAl.csv'
)

file_contents = smartsheet.reports.get_as_csv(
  report_id: 4583173393803140
)

File.open('output.csv', 'w') {|f| f.write(file_contents)}

Example response

# See local file named "output.csv"

// See local file named "output.csv"

// Contents of CSV file is written to "outputStream"

// Contents of CSV file is written to "outputStream"

# download folder contains the downloaded CSV file

# See local file named "output.csv"

GET /reports/{reportId}

Gets the report in the format specified, based on the report Id.


Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
	Accept -- must be set to one of the following values: application/vnd.ms-excel text/csv
Returns	The report file in either Excel or CSV format.
Access Scope	READ_SHEETS

List Reports

Example request: list reports

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

smartsheet.reports.listReports()
  .then(function(reportList) {
    console.log(reportList);
  })
  .catch(function(error) {
    console.log(error);
  });

PaginatedResult<Report> reports = smartsheet.ReportResources.ListReports(
  null,               // PaginationParameters
  null                // Nullable<DateTime> modifiedSince = null
);

PagedResult<Report> reports = smartsheet.reportResources().listReports(
  null,               // PaginationParameters
  null                // Date modifiedSince
);

response = ss_client.Reports.list_reports(include_all=True)
reports = response.data

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

Example response

{
  "pageNumber": 1,
  "totalPages": 1,
  "totalCount": 2,
  "data": [

Smartsheet API 2.0

Overview

Introduction

How Do I Start?

HTTP and REST

RESTful Architecture

HTTP Verbs

HTTP Status Codes

HTTP Headers

Query Strings

Authentication and Access Tokens

Dates and Times

Sheets/Columns/Rows/Cells

Object Details vs List Summaries

Versioning and Changes

Getting Started

Make Your First API Call

How to Read a Sheet Response

SDKs and Sample Code

Permission Levels

Access Levels

Assume User

Third-party App Development

First Steps

Open Developer Tools

Register Your App Using Developer Tools

Access Scopes

OAuth Flow

Request an Authorization Code

If the User Clicks Allow

If the User Clicks Deny

Request an Access Token

Refresh an Access Token

OAuth Error Types

Work at Scale

Bulk Operations

Optional Bulk Operations

Partial Success

Paging

Paging Query String Parameters

Paged Responses

Rate Limiting

Handle "Rate limit exceeded" Error

Avoid Executing "Rapid Fire" Updates

Execute Requests Serially

API Reference

Attachments

Objects

Attachment Object

Post an Attachment

Multipart Uploads

Simple Uploads

Attach File to Comment

Attach File to Row

Attach File to Sheet

Attach URL to Comment

Attach URL to Row

Attach URL to Sheet

Delete Attachment

Get Attachment

List Attachments

List Discussion Attachments

List Row Attachments

Versioning

Attach New Version

Delete All Versions

List Versions

Automation Rules

Objects

AutomationRule Object

AutomationAction Object

Delete an Automation Rule

Get an Automation Rule

List All Automation Rules

Update an Automation Rule

Related Items

Disabled Reasons for Automation Rules

Cells

Objects

Cell Object