Smartsheet API 2.0

Updated 2019-08-14

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 user accounts and organization account

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

How Do I Start?

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

• Smartsheet Developer Portal: If registering, use a different email address from your paid Smartsheet account so you can test the API and make API calls
• Developer Newsletter (subscribe while at the Developer Portal using the "Get Developer Updates" form)
• StackOverflow using the "smartsheet-api" tag
• Contact us at 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 = smartsheet_client.Sheets.list_sheets(include="attachments,source", include_all=True)
sheets = response.data

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

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

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

Authentication and Access Tokens

Example request: authentication and access tokens

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

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

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

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

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

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

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

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

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

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

require 'smartsheet'

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

Example response

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

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

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

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

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

Authorization: Bearer ll352u9jujauoqz4gstvsae05

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

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.

Working with Smartsheet Gov Accounts

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

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

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

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

Getting Started

Make Your First API Call

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

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

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

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

In Postman, the request looks like this:

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

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

How to Read a Sheet Response

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

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

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

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

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

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

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

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

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

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

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

SDKs and Sample Code

Install the SDK

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

npm install smartsheet

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

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

$ pip install smartsheet-python-sdk

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

# And then execute
$ bundle

Load the client

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

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

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

// Initialize client
String accessToken = "ll352u9jujauoqz4gstvsae05";

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

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

// Initialize client
String accessToken = "ll352u9jujauoqz4gstvsae05";

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

import smartsheet

# Initialize client
smartsheet_client = smartsheet.Smartsheet(access_token)

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

require 'smartsheet'
require 'logger'

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

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

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

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

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

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

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

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

Permission Levels

Access Levels

Sheets, templates, and workspaces have an accessLevel attribute that describes the current user's access level to that object. This corresponds directly to the sharing and access controls of Smartsheet that are available through the Smartsheet UI. The accessLevel attribute has one of the following values:

Value	Description
ADMIN	The user can edit and share the resource, and can alter the structure of the resource as well.
EDITOR	The user can edit the resource, but cannot alter the structure of, delete, or share the resource.
EDITOR_SHARE	The same as EDITOR, but with the ability to share the resource to other users.
OWNER	The user has complete control over the resource.
VIEWER	The user has read-only access to the resource.

Assume User

Example: assume user

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

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

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

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

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

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

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

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

Third-party App Development

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

First Steps

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

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

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

Open Developer Tools

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

Register Your App Using Developer Tools

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

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

Access Scopes

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

The access scopes are as follows:

Access Scope	Description
ADMIN_SHEETS	Modify sheet structure, including column definition, publish state, etc.
ADMIN_SIGHTS	Modify Sights/dashboards structure.
ADMIN_USERS	Add and remove users from your Smartsheet organization account; create groups and manage membership.
ADMIN_WEBHOOKS	Create, delete, and update webhooks; get all webhooks; reset shared secret.
ADMIN_WORKSPACES	Create and manage workspaces and folders, including sharing.
CREATE_SHEETS	Create new sheets.
CREATE_SIGHTS	Create new 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 account.
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:

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]

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

Successful Response:

// The user sees your app's consent page

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

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

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

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

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

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

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

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

If the User Clicks Allow

Successful Response:

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

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

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

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

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

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

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

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

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

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

If the User Clicks Deny

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

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

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

Request an Access Token

Request an access token:

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

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

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 = smartsheet_client.Sheets.list_sheets(include="attachments,source", include_all=True)
sheets = response.data

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

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

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

Paged Responses

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

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

Rate Limiting

Handle "Rate limit exceeded" Error

To prevent abuse and undue stress on the Smartsheet servers, the API has a rate limiting feature (sometimes called throttling) that restricts users to 300 requests per minute per access token. Certain resource intensive operations, such as attaching a file and getting cell history, count as 10 requests. Smartsheet reserves the right to enforce this limit depending on the load on our systems. If and when the limit is enforced, any requests that exceed this limit are rejected with an 429 HTTP status code, along with the following JSON response body:

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

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

Avoid Executing "Rapid Fire" Updates

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

Execute Requests Serially

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

API Reference

Attachments

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

Objects

Attachment Object

Example: Attachment object

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

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

Post an Attachment

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

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

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

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

Multipart Uploads

A multipart upload request must include the following HTTP headers:

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

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

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

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

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

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

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

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

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

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

Simple Uploads

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

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

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

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

< Binary content for file >

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

Attach File to Comment

Example request: attach file to comment

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

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

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

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

Attachment attachment = smartsheet.SheetResources.CommentResources.AttachmentResources.AttachFile(
  9283173393803140,           // 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 = smartsheet_client.Attachments.attach_file_to_comment(
  9283173393803140,       # sheet_id
  1234567890234568,       # comment_id
  ('ProgressReport.docx', 
    open('/path/to/ProgressReport.docx', 'rb'), 
    'application/msword')
)

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

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

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

Example response

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

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

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

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

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

Attach File to Row

Example request: attach file to row

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

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

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

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

Attachment attachment = smartsheet.SheetResources.RowResources.AttachmentResources.AttachFile(
  9283173393803140,           // 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 = smartsheet_client.Attachments.attach_file_to_row(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  ('ProgressReport.docx', 
    open('/path/to/ProgressReport.docx', 'rb'), 
    'application/msword')
)

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

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

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

Example response

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

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

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

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

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

Attach File to Sheet

Example request: attach file to sheet

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

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

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

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

Attachment attachment = smartsheet.SheetResources.AttachmentResources.AttachFile(
  9283173393803140,           // 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 = smartsheet_client.Attachments.attach_file_to_sheet(
  9283173393803140,       # sheet_id
  ('ProgressReport.docx', 
    open('/path/to/ProgressReport.docx', 'rb'), 
    'application/msword')
)

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

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

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

Example response

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

POST /sheets/{sheetId}/attachments

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

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

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

Attach URL to Comment

Example request: attach URL to comment

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

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

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

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

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

// Attach URL to comment
Attachment updatedAttachment = smartsheet.SheetResources.CommentResources.AttachmentResources.AttachUrl(
  9283173393803140,           // 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 = smartsheet.models.Attachment({
  'name': 'Search Engine',
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

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

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

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

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "attachmentType": "LINK",
    "createdAt": "2013-02-28T21:52:40-08:00",
    "description": "A popular search engine",
    "id": 1205473673275268,
    "name": "Search Engine",
    "url": "http://google.com"
  }
}

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

Attaches a URL to the comment.

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

The URL can be any of the following:

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

Attach URL to Row

Example request: attach URL to row

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

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

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

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

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

// Attach URL to row
Attachment updatedAttachment = smartsheet.SheetResources.RowResources.AttachmentResources.AttachUrl(
  9283173393803140,           // 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 = smartsheet.models.Attachment({
  'name': 'Search Engine',
  'description': 'A popular search engine.'
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

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

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

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

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "attachmentType": "LINK",
    "createdAt": "2013-02-28T21:52:40-08:00",
    "description": "A popular search engine",
    "id": 1205473673275268,
    "name": "Search Engine",
    "url": "http://google.com"
  }
}

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

Attaches a URL to the row.

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

The URL can be any of the following:

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

Attach URL to Sheet

Example request: attach URL to sheet

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

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

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

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

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

// Attach URL to sheet
Attachment updatedAttachment = smartsheet.SheetResources.AttachmentResources.AttachUrl(
  9283173393803140,           // 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 = smartsheet.models.Attachment({
  'name': 'Search Engine',
  'description': 'A popular search engine.',
  'attachment_type': 'LINK',
  'url': 'http://www.google.com'
})

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

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

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

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "attachmentType": "LINK",
    "createdAt": "2013-02-28T21:52:40-08:00",
    "description": "A popular search engine",
    "id": 1205473673275268,
    "name": "Search Engine",
    "url": "http://google.com"
  }
}

POST /sheets/{sheetId}/attachments

Attaches a URL to the sheet.

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

The URL can be any of the following:

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

Delete Attachment

Example request: delete attachment

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

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

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

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

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

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

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

Example response

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

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

Deletes the attachment specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

Get Attachment

Example request: get attachment

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

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

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

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

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

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

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

Example response

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

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

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

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

List Attachments

Example request: list attachments

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

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

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

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

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

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

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

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

Example response

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

GET /sheets/{sheetId}/attachments

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

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

List Discussion Attachments

Example request: list discussion attachments

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

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

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

// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.DiscussionResources.AttachmentResources.ListAttachments(
  9283173393803140,               // 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 = smartsheet_client.Attachments.list_discussion_attachments(
  9283173393803140,       # sheet_id 
  1234567890123456,       # discussion_id 
  include_all=True)
attachments = response.data

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

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

Example response

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

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

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

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

List Row Attachments

Example request: list row attachments

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

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

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

// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.RowResources.AttachmentResources.ListAttachments(
  2252168947361668,               // 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 = smartsheet_client.Attachments.list_row_attachments(
  2252168947361668,       # sheet_id 
  4293147074291588,       # row_id 
  include_all=True)
attachments = response.data

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

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

Example response

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

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

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

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

Versioning

Attach New Version

Example request: attach new version

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

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

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

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

Attachment attachment = smartsheet.SheetResources.AttachmentResources.VersioningResources.AttachNewVersion(
  9283173393803140,               // 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 = smartsheet_client.Attachments.attach_new_version(
  9283173393803140,       # sheet_id
  0123456789123456,       # attachment_id
  ('ProgressReport.docx',
    open('/path/to/ProgressReport.docx', 'rb'),
    'application/msword')
)

updated_attachment = response.result

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

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

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

Example response

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

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

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

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

Delete All Versions

Example request: delete all versions

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

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

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

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

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

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

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

Example response

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

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

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

List Versions

Example request: list versions

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

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

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

// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.AttachmentResources.VersioningResources.ListVersions(
  2252168947361668,               // 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 = smartsheet_client.Attachments.list_attachment_versions(
  2252168947361668,       # sheet_id 
  5510069950408580,       # attachment_id
  include_all=True)
versions = response.data

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

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

Example response

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

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

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

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

Automation Rules

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

Objects

AutomationRule Object

Example: AutomationRule object

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

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

AutomationAction Object

Example: AutomationAction object

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

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

Delete an Automation Rule

Example request: delete an automation rule

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

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

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

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

Related Items

Disabled Reasons for Automation Rules

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

Cells

A collection of cells comprises each row in a sheet.

Objects

Cell Object

Example: Cell object

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

columnId	number	The Id of the column that the cell is located in
columnType	string	See type definition on the Column object. Only returned if the include query string parameter contains columnType.
conditionalFormat	string	The format descriptor describing this cell's conditional format (see Formatting). Only returned if the include query string parameter contains format and this cell has a conditional format applied.
displayValue	string	Visual representation of cell contents, as presented to the user in the UI. See Cell Reference.
format	string	The format descriptor (see Formatting) Only returned if the include query string parameter contains format and this cell has a non-default format applied.
formula	string	The formula for a cell, if set. 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 = smartsheet_client.Cells.get_cell_history(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  4567890123456789,       # column_id
  include_all=True)
revisions = response.data

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

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

Example response

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

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

Gets the cell modification history.

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

Update Cells

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

Related Items

Cell Links

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

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

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

Cell Reference

Cell Value Representation

Cell objects retrieved through the Smartsheet APIs have two main attributes representing cell values: Cell.value, and Cell.displayValue. A third attribute, Cell.objectValue is currently used only for adding and updating predecessors, or for multi-contact 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"
smartsheet_client.Cells.add_image_to_cell(sheet_id, row_id, column_id, caution_pic, file_type)

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

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

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

Example response

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

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

Uploads an image to the specified cell within a sheet.

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

Download Cell Image

Example request: download cell image

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

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

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

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

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

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

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

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

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

// Step 2: Get image info from cell

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

// Step 3: Build list of image URLs

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

// Step 4: Download the image

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

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 = smartsheet_client.Sheets.get_row(sheet_id, row_id)
cell = row.get_column(column_id)
image = cell.image
image_id = image.id

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

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

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

require 'open-uri'

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

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

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

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

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

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

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

Step 1. Locate the cell

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

Step 2. Obtain the image Id

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

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

Step 3. Obtain a temporary image URL

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

Step 4. Download the image

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

List Image URLs

Example request: list image URLs

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

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

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

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

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

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

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

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

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

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

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

Example response

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

POST /imageurls

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

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

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

Remove Image from Cell

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

Update Cell Image

A cell image can be updated as follows:

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

Columns

A column is a component of a sheet or report.

Objects

Column Object

Example: Column object

{
  "id": 7960873114331012,
  "version": 0,
  "index": 0,
  "symbol": "STAR",
  "title": "Favorite",
  "description": "Sample description",
  "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
description	string	Column description.
format	string	The format descriptor (see Formatting) Only returned if the include query string parameter contains format and this column has a non-default format applied to it.
hidden	Boolean	Indicates whether the column is hidden
index	number	Column index or position. This number is zero-based.
locked	Boolean	Indicates whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin.
lockedForUser	Boolean	Indicates whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.
options	string[]	Array of the options available for the column
primary	Boolean	Returned only if the column is the Primary Column (value = true)
symbol	string	When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns.
tags	string[]	Set of tags to indicate special columns. Each element in the array is set to one of the following values: CALENDAR_END_DATE CALENDAR_START_DATE CARD_DONE GANTT_ALLOCATION GANTT_ASSIGNED_RESOURCE GANTT_DISPLAY_LABEL GANTT_DURATION GANTT_END_DATE GANTT_PERCENT_COMPLETE GANTT_PREDECESSOR GANTT_START_DATE
title	string	Column title
validation	Boolean	Indicates whether validation has been enabled for the column (value = true)
version	number	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 = smartsheet.models.Column({
  'title': 'New Picklist Column 1',
  'type': 'PICKLIST',
  'options': [
    'First',
    'Second',
    'Third'
  ],
  'index': 4
})

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

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

# Define options
body = {
  title: 'New Picklist Column 1',
  type: 'PICKLIST',
  options: [
    'First',
    'Second',
    'Third'
  ],
  index: 4
},
{
  title: "New Date Column",
  type: 'DATE',
  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 index (zero-based) autoNumberFormat (optional) description (optional) locked (optional) options (optional) symbol (optional) systemColumnType (optional) validation (optional) width (optional)
Returns	Result object containing the newly created columns -- either a single Column object or an array of Column objects, corresponding to what was specified in the request.
Access Scope	ADMIN_SHEETS

Delete Column

Example request: delete column

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

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

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

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

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

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

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

Example response

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

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

Deletes the column specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_SHEETS

Get Column

Example request: get column

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

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

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

// Sample 1: Omit 'include' parameter
Column column = smartsheet.SheetResources.ColumnResources.GetColumn(
  9283173393803140,               // 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 = smartsheet_client.Sheets.get_column(
  9283173393803140,       # sheet_id
  7960873114331012)       # column_id

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

Example response

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

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

Gets the column specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	level (optional): specifies whether multi-contact data is returned in a backwards-compatible, text format (level=0, default) or as multi-contact data (level=1).
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 = smartsheet_client.Sheets.get_columns(
  9283173393803140,       # sheet_id
  include_all=True)
columns = response.data

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

Example response

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

GET /sheets/{sheetId}/columns

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

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

Update Column

Example request: update column

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X PUT \
-d '{"title":"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 = smartsheet.models.Column({
  'title': 'First Column',
  'type': 'PICKLIST',
  'options': ["One", "Two"],
  'index': 0
})

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

updated_column = response.result

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

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

Example response

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

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

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

NOTES:

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

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

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

Related Items

Column Types

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 = smartsheet_client.Discussions.add_comment_to_discussion(
  2252168947361668,       # sheet_id
  3962273862576004,       # discussion_id
  smartsheet.models.Comment({
    'text': 'This is a new comment.'
  })
)

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

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

Example request: add comment (with attachment)

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

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

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

// Add comment (with attachment) to discussion
Comment newComment = smartsheet.SheetResources.DiscussionResources.CommentResources.AddCommentWithAttachment(
  2252168947361668,                   // 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 = smartsheet.models.Comment({
  'text': 'This is a new comment.'
})

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

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

Example response

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

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

Adds a comment to a discussion.

Creating a Comment without an Attachment

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

Creating a Comment with an Attachment

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

Edit Comment

Example request: edit comment

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

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

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

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

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

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

[todo]

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

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

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

Example response

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

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

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

Updating a Comment

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

Delete Comment

Example request: delete comment

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

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

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

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

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

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

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

Example response

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

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

Deletes the comment specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

Get Comment

Example request: get comment

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

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

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

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

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

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

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

Example response

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

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

Gets the comment specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Comment object
Access Scope	READ_SHEETS

Related Items

A comment can contain one or more attachments.

Comment Attachments

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

Contacts

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

Objects

Contact Object

Example: Contact object

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

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

Get Contact

Example request: get contact

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

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

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

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

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

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

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

Example response

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

GET /contacts/{contactId}

Gets the specified contact.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Contact object
Access Scope	READ_CONTACTS

List Contacts

Example request: list contacts

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

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

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

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

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

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

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

Example response

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

GET /contacts

Gets a list of the user's Smartsheet contacts.

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

Cross-sheet References

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

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

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

Objects

CrossSheetReference Object

Example: CrossSheetReference object

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

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

Create Cross-sheet References

Example request: create cross-sheet references

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

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

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

// Not yet implemented

// Not yet implemented

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

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

Example response

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

POST /sheets/{sheetId}/crosssheetreferences

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

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

Get Cross-sheet Reference

Example request: get cross-sheet references

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

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

// Not yet implemented

// Not yet implemented

result = smartsheet_client.Sheets.get_cross_sheet_reference(
  9283173393803140, 8157685695702916)

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

result = smartsheet_client.Sheets.list_cross_sheet_references(
  9283173393803140)

smartsheet.sheets.cross_sheet_references.list(
  sheet_id: 9283173393803140
)

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 6,
  "data": [
    {
      "id": 2545778347534212,
      "status": "OK",
      "name": "Data Sheet Range 1",
      "sourceSheetId": 1244271622809476,
      "startColumnId": 6905486478993284,
      "endColumnId": 545911223936900
    },
    {
      "id": 8157685695702916,
      "status": "OK",
      "name": "Sample Time Log Sheet Range 1",
      "sourceSheetId": 154378742065028,
      "startRowId": 4089096300717956,
      "endRowId": 2681721417164676,
      "startColumnId": 824812248557444,
      "endColumnId": 824812248557444
    }
  ]
}

GET /sheets/{sheetId}/crosssheetreferences

Lists all cross-sheet references for the sheet.

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

Dashboards

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 = smartsheet_client.Discussions.create_discussion_on_row(
  9283173393803140,           # sheet_id
  0123456789012345,           # row_id
  smartsheet.models.Discussion({
    'comment': smartsheet.models.Comment({
      'text': 'This text is the body of the first comment'
    })
  })
)

# Set options
body = {
  comment: {
    text: 'This text is the body of the first comment'
  }
}

# Create discussion on row
response = smartsheet.sheets.discussions.create_on_row(
  sheet_id: 4583173393803140,
  row_id: 4293147074291588,
  body: body
)
new_discussion = response[:result]

Example request: create discussion on row (with attachment)

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

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

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
  Comment = new Comment
  {
    Text = "This text is the body of the first comment"
  },
  Comments = null         // workaround for SDK issue
};

// Add discussion to row
Discussion newDiscussion = smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussionWithAttachment(
  9283173393803140,                   // 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 = smartsheet_client.Discussions.create_discussion_on_row_with_attachment(
  9283173393803140,       # sheet_id
  0123456789012345,       # row_id
  smartsheet.models.Discussion({
    'comment': smartsheet.models.Comment({
      'text': 'This text is the body of the first comment'
    })
  }),
  ('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')
)

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

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "comments": [{
            "createdAt": "2013-02-28T22:00:56-08:00",
            "createdBy": {
                "email": "jane.doe@smartsheet.com",
                "name": "Jane Doe"
            },
            "id": 4583173393803140,
            "modifiedAt": "2013-02-28T22:00:56-08:00",
            "text": "This text is the body of the first comment"
        }],
        "id": 4583173393803140,
        "title": "This text is the body of the first comment"
    },
    "version": 12
}

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

Creates a new discussion on a row.

Creating a Discussion without an Attachment

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Discussion object with the following attribute: comment (Comment object)
Returns	Result object containing Discussion object for the newly created discussion
Access Scope	WRITE_SHEETS

Creating a Discussion with an Attachment

Headers	See Multipart Uploads for information about headers that are required for multipart requests.
Request Body	Request body should contain parts with the following names: discussion: JSON Discussion object with the following attributes: title (string), must be 100 characters in length or less comment (Comment object) file: (optional) file to attach to the new comment See Multipart Uploads for more information on parts.
Returns	Result object containing a Discussion object for the newly created discussion, which contains a Comment object for the initial discussion comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment.
Access Scope	WRITE_SHEETS

Create Discussion on Sheet

Example request: create discussion on sheet (without attachment)

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

// Specify discussion
var discussion = {
  "comment": {
    "text": "This text is the body of the first comment"
  }
};

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

// Add discussion to sheet
smartsheet.sheets.createDiscussion(options)
  .then(function(newDiscussion) {
    console.log(newDiscussion);
  })
  .catch(function(error) {
    console.log(error);
  });

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
  Comment = new Comment
  {
    Text = "This text is the body of the first comment"
  },
  Comments = null         // workaround for SDK issue
};

// Add discussion to sheet
Discussion newDiscussion = smartsheet.SheetResources.DiscussionResources.CreateDiscussion(
  9283173393803140,                   // 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 = smartsheet_client.Discussions.create_discussion_on_sheet(
  9283173393803140,           # sheet_id
  smartsheet.models.Discussion({
    'comment': smartsheet.models.Comment({
      'text': 'This text is the body of the first comment'
    })
  })
)

# Set options
body = {
  comment: {
    text: 'This text is the body of the first comment'
  }
}

# Create discussion on sheet
response = smartsheet.sheets.discussions.create_on_sheet(
  sheet_id: 4583173393803140,
  body: body
)
new_discussion = response[:result]

Example request: create discussion on sheet (with attachment)

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F 'discussion={ "comment": { "text": "This text is the body of the first comment" } };type=application/json' \
-F "file=@file_to_attach;type=application/octet-stream" \

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

// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
  Comment = new Comment
  {
    Text = "This text is the body of the first comment"
  },
  Comments = null         // workaround for SDK issue
};

// Add discussion (including comment with attachment) to sheet
Discussion newDiscussion = smartsheet.SheetResources.DiscussionResources.CreateDiscussionWithAttachment(
  9283173393803140,                   // 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 = smartsheet_client.Discussions.create_discussion_on_sheet_with_attachment(
  9283173393803140,           # sheet_id
  smartsheet.models.Discussion({
    'comment': smartsheet.models.Comment({
      'text': 'This text is the body of the first comment'
    })
  }),
  ('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')
)

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

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "comments": [{
            "createdAt": "2013-02-28T22:00:56-08:00",
            "createdBy": {
                "email": "jane.doe@smartsheet.com",
                "name": "Jane Doe"
            },
            "id": 4583173393803140,
            "modifiedAt": "2013-02-28T22:00:56-08:00",
            "text": "This text is the body of the first comment"
        }],
        "id": 4583173393803140,
        "title": "This text is the body of the first comment"
    },
    "version": 12
}

POST /sheets/{sheetId}/discussions

Creates a new discussion on a sheet.

Creating a Discussion without an Attachment

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Discussion object with the following attribute: comment (Comment object)
Returns	Result object containing Discussion object for the newly created discussion
Access Scope	WRITE_SHEETS

Creating a Discussion with an Attachment

Headers	See Multipart Uploads for information about headers that are required for multipart requests.
Request Body	Request body should contain parts with the following names: discussion: JSON Discussion object with the following attributes: title (string), must be 100 characters in length or less comment (Comment object) file: (optional) file to attach to the new comment See Multipart Uploads for more information on parts.
Returns	Result object containing a Discussion object for the newly created discussion, which contains a Comment object for the initial discussion comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment.
Access Scope	WRITE_SHEETS

Delete Discussion

Example request: delete discussion

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

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

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

smartsheet.SheetResources.DiscussionResources.DeleteDiscussion(
  9283173393803140,               // long sheetId
  0123456789012345                // long discussionId
);

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

smartsheet_client.Discussions.delete_discussion(
  9283173393803140,       # sheet_id
  0123456789012345)       # discussion_id

smartsheet.sheets.discussions.delete(
  sheet_id: 4583173393803140,
  discussion_id: 3962273862576004
)

Example response

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

DELETE /sheets/{sheetId}/discussions/{discussionId}

Deletes the discussion specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	WRITE_SHEETS

List Discussions

Example request: list discussions

curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions?include=comments,attachments' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

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

// List discussions
smartsheet.sheets.getDiscussions(options)
  .then(function(discussionList) {
    console.log(discussionList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<Discussion> results = smartsheet.SheetResources.DiscussionResources.ListDiscussions(
  9283173393803140,               // 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 = smartsheet_client.Discussions.get_all_discussions(
  9283173393803140,       # sheet_id
  include_all=True)
discussions = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Discussions.get_all_discussions(
  9283173393803140,       # sheet_id
  page_size=10,
  page=1)
pages = response.total_pages
discussions = response.data

response = smartsheet.sheets.discussions.list(
  sheet_id: 4583173393803140
)
discussions = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 1,
    "data": [
    {
      "id": 3138415114905476,
      "title": "Lincoln",
      "comments": [
        {
          "id": 7320407591151492,
          "text": "16th President",
          "createdBy": {
            "name": "Test User",
            "email": "tester@smartsheet.com"
          },
          "createdAt": "2015-01-12T18:23:02-08:00",
          "modifiedAt": "2015-01-12T18:23:02-08:00"
        }
      ],
      "commentCount" : 1,
      "accessLevel": "OWNER",
      "parentType": "ROW",
      "parentId": 4508369022150532,
      "lastCommentedUser": {
        "name": "Test User",
        "email": "tester@smartsheet.com"
      },
      "createdBy": {
        "name": "Test User",
        "email": "tester@smartsheet.com"
      },
      "readOnly": false,
      "lastCommentedAt": "2015-01-12T18:23:02-08:00"
    }
    ]
}

GET /sheets/{sheetId}/discussions

Gets a list of all discussions associated with the specified sheet. Remember that discussions are containers for the conversation thread. To see the entire thread, use the include=comments parameter.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of optional elements to include in the response: attachments - effective only if comments is present, otherwise ignored comments This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Discussion objects
Access Scope	READ_SHEETS

Get Discussion

Example request: get discussion

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

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

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

Discussion discussion = smartsheet.SheetResources.DiscussionResources.GetDiscussion(
  9283173393803140,               // long sheetId
  0123456789012345                // long discussionId
);

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

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

# discussion is an instance of smartsheet.models.Discussion

discussion = smartsheet.sheets.discussions.get(
  sheet_id: 4583173393803140,
  discussion_id: 3962273862576004
)

Example response

{
  "title": "This is a new discussion",
  "id": 2331373580117892,
  "comments": [
    {
      "id": 2331373580117892,
      "text": "This text is the body of the discussion",
      "createdBy": {
        "email": "john.doe@smartsheet.com"
      },
      "modifiedAt": "2012-07-25T00:02:42-07:00"
    }
  ],
  "commentCount" : 1
}

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

Gets the discussion specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Discussion object
Access Scope	READ_SHEETS

List Row Discussions

Example request: list row discussions

curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions?include=comments,attachments' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

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

// List row discussions
smartsheet.sheets.getRowDiscussions(options)
  .then(function(discussionList) {
    console.log(discussionList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<Discussion> results = smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(
  2252168947361668,                   // 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 = smartsheet_client.Discussions.get_row_discussions(
  2252168947361668,               # sheet_id
  4293147074291588,               # row_id
  include_all=True)
discussions = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Discussions.get_row_discussions(
  2252168947361668,               # sheet_id
  4293147074291588,               # row_id
  page_size=10)
pages = response.total_pages          # starts on page 1 by default
discussions = response.data

response = smartsheet.sheets.discussions.list_row_discussions(
  sheet_id: 4583173393803140,
  row_id: 4293147074291588
)
discussions = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 1,
    "data": [
    {
      "id": 3138415114905476,
      "title": "Lincoln",
      "comments": [
        {
          "id": 7320407591151492,
          "text": "16th President",
          "createdBy": {
            "name": "Test User",
            "email": "tester@smartsheet.com"
          },
          "createdAt": "2015-01-12T18:23:02-08:00",
          "modifiedAt": "2015-01-12T18:23:02-08:00"
        }
      ],
      "commentCount" : 1,
      "accessLevel": "OWNER",
      "parentType": "ROW",
      "parentId": 4508369022150532,
      "lastCommentedUser": {
        "name": "Test User",
        "email": "tester@smartsheet.com"
      },
      "createdBy": {
        "name": "Test User",
        "email": "tester@smartsheet.com"
      },
      "readOnly": false,
      "lastCommentedAt": "2015-01-12T18:23:02-08:00"
    }
    ]
}

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

Gets a list of all discussions associated with the specified row. Remember that discussions are containers for the conversation thread. To see the entire thread, use the include=comments parameter.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of optional elements to include in the response: attachments - effective only if comments is present, otherwise ignored comments This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Discussion objects
Access Scope	READ_SHEETS

Related Items

A discussion is a collection of one or more comments, each of which may contain attachments.

Discussion Attachments

For details about working with the attachments within a discussion, see Attachments.

Discussion Comments

For details about working with a discussion's comments, see Comments.

Favorites

Smartsheet allows users to "star" 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 = smartsheet_client.Favorites.add_favorites([
  smartsheet.models.Favorite({
    'type': 'sheet',
    'object_id': 8400677765441412
  })
])

# Specify favorites
body = {
  type: 'sheet',
  object_id: 8400677765441412
}

# Add items to favorites
response = smartsheet.favorites.add(
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
        "type": "sheet",
        "objectId": 8400677765441412
    }]
}

POST /favorites

Adds one or more items to the user's list of favorite items. This operation supports both single-object and bulk semantics. For more information, see Optional Bulk Operations.

If called with a single Favorite object, and that favorite already exists, error code 1129 is returned. If called with an array of Favorite objects, any objects specified in the array that are already marked as favorites are ignored and omitted from the response.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Favorite object or an array of Favorite objects, with the following attributes: objectId type
Returns	Result object containing objects that were marked as favorites -- either a single Favorite object or an array of Favorite objects, corresponding to what was specified in the request.
Access Scope	ADMIN_WORKSPACES

List Favorites

Example request: list favorites

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

smartsheet.favorites.listFavorites()
  .then(function(favoritesList) {
    console.log(favoritesList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Favorite> results = smartsheet.FavoriteResources.ListFavorites(
  null                // PaginationParameters
);

// Omit pagination parameters
PagedResult<Favorite> results = smartsheet.favoriteResources().listFavorites(
  null        // PaginationParameters
);

response = smartsheet_client.Favorites.list_favorites(include_all=True)
faves = response.data

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

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "type": "sheet",
            "objectId": 5897312590423940
        },
        {
            "type": "folder",
            "objectId": 1493728255862660
        }
    ]
}

GET /favorites

Gets a list of all of the user's favorite items.

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

Remove Favorite

Remove Favorite Folder

Example request: remove favorite folder

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

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

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

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.FOLDER,
  new long[] { 2252168947361668 }   // long folderId
);

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

smartsheet_client.Favorites.remove_favorites(
  'folder', 
  2252168947361668        # folder_id
)

smartsheet.favorites.remove_folder(
  folder_id: 2252168947361668
)

Example response

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

DELETE /favorites/folder/{folderId}

Removes a single folder from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite Report

Example request: remove favorite report

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

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

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

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.REPORT,
  new long[] { 2252168947361668 }       // long reportId
);

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

smartsheet_client.Favorites.remove_favorites(
  'report', 
  2252168947361668        # report_id
)

smartsheet.favorites.remove_report(
  report_id: 2252168947361668
)

Example response

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

DELETE /favorites/report/{reportId}

Removes a single report from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite Sheet

Example request: remove favorite sheet

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

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

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

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.SHEET,
  new long[] { 2252168947361668 }   // long sheetId
);

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

smartsheet_client.Favorites.remove_favorites(
  'sheet', 
  2252168947361668        # sheet_id
)

smartsheet.favorites.remove_sheet(
  sheet_id: 2252168947361668
)

Example response

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

DELETE /favorites/sheet/{sheetId}

Removes a single sheet from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite 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]

smartsheet_client.Favorites.remove_favorites(
  'sight',
  6327127650920324        # sight_id
)

smartsheet.favorites.remove_sight(
  sight_id: 6327127650920324
)

Example response

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

DELETE /favorites/sights/{sightId}

Removes a single 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
);

smartsheet_client.Favorites.remove_favorites(
  'template', 
  2252168947361668        # template_id
)

smartsheet.favorites.remove_template(
  template_id: 2252168947361668
)

Example response

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

DELETE /favorites/template/{templateId}

Removes a single template from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Favorite Workspace

Example request: remove favorite workspace

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

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

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

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.WORKSPACE,
  new long[] { 2252168947361668 }   // long workspaceId
);

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

smartsheet_client.Favorites.remove_favorites(
  'workspace', 
  2252168947361668        # workspace_id
)

smartsheet.favorites.remove_workspace(
  workspace_id: 2252168947361668
)

Example response

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

DELETE /favorites/workspace/{workspaceId}

Removes a single workspace from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Multiple Favorites

Remove Multiple Favorite Folders

Example request: remove multiple favorite folders

curl 'https://api.smartsheet.com/2.0/favorites/folder?objectIds=folderId1,folderId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

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

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.FOLDER,
  new long[] { 2252168947361668, 2252168947361669 }     // folderIds
);

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

smartsheet_client.Favorites.remove_favorites(
  'folder', 
  [2252168947361668, 2252168947361669]        # folder_ids
)

smartsheet.favorites.remove_folders(
  folder_ids: [2252168947361668, 2252168947361669]
)

Example response

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

DELETE /favorites/folder

Removes multiple folders from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Multiple Favorite Reports

Example request: remove multiple favorite reports

curl 'https://api.smartsheet.com/2.0/favorites/report?objectIds=reportId1,reportId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

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

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.REPORT,
  new long[] { 2252168947361668, 2252168947361669 }    // reportIds
);

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

smartsheet_client.Favorites.remove_favorites(
  'report', 
  [2252168947361668, 2252168947361669]        # report_ids
)

smartsheet.favorites.remove_reports(
  report_ids: [2252168947361668, 2252168947361669]
)

Example response

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

DELETE /favorites/report

Removes multiple reports from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Multiple Favorite Sheets

Example request: remove multiple favorite sheets

curl 'https://api.smartsheet.com/2.0/favorites/sheet?objectIds=sheetId1,sheetId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

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

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.SHEET,
  new long[] { 2252168947361668, 2252168947361669 }    // sheetIds
);

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

smartsheet_client.Favorites.remove_favorites(
  'sheet', 
  [2252168947361668, 2252168947361669]        # sheet_ids
)

smartsheet.favorites.remove_sheets(
  sheet_ids: [2252168947361668, 2252168947361669]
)

Example Response:

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

DELETE /favorites/sheet

Removes multiple sheets from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Multiple Favorite 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]

smartsheet_client.Favorites.remove_favorites(
  'sight',
  [6327127650920324, 3404239197235076]        # sight_ids
)

smartsheet.favorites.remove_sights(
  sight_ids: [6327127650920324, 2591554075418573]
)

Example response

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

DELETE /favorites/sights

Removes multiple 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
);

smartsheet_client.Favorites.remove_favorites(
  'template', 
  [2252168947361668, 2252168947361669]        # template_ids
)

smartsheet.favorites.remove_templates(
  template_ids: [2252168947361668, 2252168947361669]
)

Example response

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

DELETE /favorites/template

Removes multiple templates from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Remove Multiple Favorite Workspaces

Example request: remove multiple favorite workspaces

curl 'https://api.smartsheet.com/2.0/favorites/workspace?objectIds=workspaceId1,workspaceId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  queryParameters: {
    objectIds: "2252168947361668,2252168947361669"
  }
};

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

smartsheet.FavoriteResources.RemoveFavorites(
  ObjectType.WORKSPACE,
  new long[] { 2252168947361668, 2252168947361669 }    // workspaceIds
);

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

smartsheet_client.Favorites.remove_favorites(
  'workspace', 
  [2252168947361668, 2252168947361669]        # workspace_ids
)

smartsheet.favorites.remove_workspaces(
  workspace_ids: [2252168947361668, 2252168947361669]
)

Example response

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

DELETE /favorites/workspace

Removes multiple workspaces from the user's list of favorite items.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Folders

A folder can exist in a user's Sheets folder (Home), in a folder, or in a workspace.

Objects

Folder Object

Example: Folder object

{
  "id": 7116448184199044,
  "name": "Projects",
  "permalink": "https://app.smartsheet.com/b/home?lx=B0_lvAtnWygeMrWr4Rfoa",
  "sheets": []
}

id	number	Folder Id
favorite	Boolean	Returned only if the user has marked the folder as a favorite in their "Home" tab (value = true)
folders	Folder[]	Array of Folder objects
name	string	Folder name
permalink	string	URL that represents a direct link to the folder in Smartsheet
reports	Report[]	Array of Report objects
sheets	Sheet[]	Array of Sheet objects
sights	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 = smartsheet_client.Folders.copy_folder(
  2252168947361668,                           # folder_id
  smartsheet.models.ContainerDestination({
    'destination_id': 7960873114331012,
    'destination_type': 'folder',
    'new_name': 'newFolderName'
  })
)

# Specify destination information
body = {
  destination_type: 'folder',
  destination_id: 7960873114331012,
  new_name: 'newFolderName'
}

# Copy folder
response = smartsheet.folders.copy(
  folder_id: 2252168947361668,
  body: body
)

Example response

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

POST /folders/{folderId}/copy

Creates a copy of the specified folder.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of elements to copy: attachments cellLinks data -- includes formatting discussions -- includes comments filters forms ruleRecipients -- includes notification recipients, must also include rules when using this attribute rules -- includes notifications and workflow rules shares all - deprecated NOTE: Cell history is not copied, regardless of which include parameter values are specified.
	skipRemap (optional) -- comma-separated list of references to NOT re-map for the newly created folder: cellLinks reports sheetHyperlinks sights By default, all cell links, 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 = smartsheet_client.Home.create_folder('New Folder')

body = {
  name: 'New Folder'
}

new_folder = smartsheet.folders.create(body: body)

Example response

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

POST /home/folders

Creates a folder in the user's Sheets folder (Home).

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

Create Folder (Subfolder)

Example request: create folder (subfolder)

curl https://api.smartsheet.com/2.0/folders/{folderid}/folders \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New folder"}'

// Set folder name
var folder = {
  "name": "New folder"
};

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

// Create folder in another folder
smartsheet.folders.createChildFolder(options)
  .then(function(newFolder) {
    console.log(newFolder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set folder name
Folder folderSpecification = new Folder { Name = "New folder" };

// Create folder in another folder
Folder newFolder = smartsheet.FolderResources.CreateFolder(
  7960873114331012,               // long destinationFolderId
  folderSpecification
);

// Set folder name
Folder folderSpecification = new Folder();
folderSpecification.setName("New Folder");

// Create folder in another folder
Folder newFolder = smartsheet.folderResources().createFolder(
  7960873114331012L,       // long destinationFolderId
  folderSpecification
);

response = smartsheet_client.Folders.create_folder_in_folder(
  7960873114331012,       # folder_id
  'New folder')

body = {
  name: 'New Folder'
}

new_folder = smartsheet.folders.create_in_folder(
  folder_id: 7960873114331012,
  body: body
)

Example response

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

POST /folders/{folderId}/folders

Creates a folder in the specified folder.

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

Create Folder (Workspace)

Example request: create folder (workspace)

curl https://api.smartsheet.com/2.0/workspaces/{workspaceid}/folders \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New folder"}'

// Set folder name
var folder = {
  "name": "New folder"
};

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

// Create folder in a workspace
smartsheet.workspaces.createFolder(options)
  .then(function(newFolder) {
    console.log(newFolder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set folder name
Folder folderSpecification = new Folder { Name = "New folder" };

// Create folder in a workspace
Folder newFolder = smartsheet.WorkspaceResources.FolderResources.CreateFolder(
  1656220827314052,               // long workspaceId
  folderSpecification
);

// Set folder name
Folder folderSpecification = new Folder();
folderSpecification.setName("New Folder");

// Create folder in a workspace
Folder newFolder = smartsheet.workspaceResources().folderResources().createFolder(
  1656220827314052L,       // long workspaceId
  folderSpecification
);

new_workspace = smartsheet_client.Workspaces.create_folder_in_workspace(
  1656220827314052,       # workspace_id
  'New folder')

body = {
  name: 'New Folder'
}

new_folder = smartsheet.folders.create_in_workspace(
  workspace_id: 1656220827314052,
  body: body
)

Example response

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

POST /workspaces/{workspaceId}/folders

Creates a folder in the specified workspace.

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

Delete Folder

Example request: delete folder

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

// Set options
var options = {
  id: 965780272637828 // Id of Folder
};

// Delete folder
smartsheet.folders.deleteFolder(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.FolderResources.DeleteFolder(
  965780272637828                 // long folderId
);

smartsheet.folderResources().deleteFolder(
  965780272637828L         // long folderId
);

smartsheet_client.Folders.delete_folder(
  7960873114331012)       # folder_id

smartsheet.folders.delete(
  folder_id: 2252168947361668
)

Example response

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

DELETE /folders/{folderId}

Deletes the folder (and its contents) specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Get Folder

Example request: get folder

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

// Set options
var options = {
  id: 7116448184199044 // Id of Folder
};

// Get folder
smartsheet.folders.getFolder(options)
  .then(function(folder) {
    console.log(folder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'include' parameter
Folder folder = smartsheet.FolderResources.GetFolder(
  7116448184199044,           // long folderId
  null                        // IEnumerable<FolderInclusion> include
);

// Sample 2: Specify 'include' parameter with value of "SOURCE"
Folder folder = smartsheet.FolderResources.GetFolder(
  7116448184199044,           // long folderId
  new FolderInclusion[] {
    FolderInclusion.SOURCE }
);

// Sample 1: Omit 'include' parameter
Folder folder = smartsheet.folderResources().getFolder(
  7116448184199044L,       // long folderId
  null)                    // EnumSet<SourceInclusion> includes
);

// Sample 2: Specify 'include' parameter with value of "SOURCE"
Folder folder = smartsheet.folderResources().getFolder(
  7116448184199044L,       // long folderId
  EnumSet.of(SourceInclusion.SOURCE))
);

folder = smartsheet_client.Folders.get_folder(
  7116448184199044)       # folder_id

folder = smartsheet.folders.get(
  folder_id: 7116448184199044
)

Example response

{
  "id": 7116448184199044,
  "name": "Projects",
  "permalink": "https://app.smartsheet.com/b/home?lx=B0_lvAtnWygeMrWr4Rfoa",
  "sheets": [
    {
      "id": 4509918431602564,
      "name": "Project Timeline",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=uWicCItTmkbxJwpCfQ5wiwW",
      "createdAt": "2015-06-05T20:05:29Z",
      "modifiedAt": "2015-06-05T20:05:43Z"
    }
  ],
  "reports": [
    {
      "id": 1653067851556740,
      "name": "Weekly report",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=v2DKrX6MH5zx2NEYHxbnlA"
    }
  ],
  "sights": [
    {
      "id": 6327127650920324,
      "name": "Employee Resource Center",
      "accessLevel": "VIEWER",
      "permalink": "https://app.smartsheet.com/b/home?lx=pgjANFWKnpXsljR6Nsts1SnUXphoZCJbZcV5Sw9DPzI",
      "createdAt": "2016-06-16T22:35:53Z",
      "modifiedAt": "2017-08-23T18:58:09Z"
    }
  ]
}

GET /folders/{folderId}

Gets the specified folder (and lists its contents).

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of optional elements to include in the response: ownerInfo - owner's email address and user Id for each sheet sheetVersion - current version number of each sheet, should not be combined with pagination source - the Source object for any sheet that was created from another report, sheet, Sight (aka dashboard), or template, if any
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 = smartsheet_client.Home.list_folders(include_all=True)
home_sheets_folders = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Home.list_folders(
  page_size=5,
  page=1)
pages = response.total_pages
folders = response.data

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

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": 9116888184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 225255547361668,
            "name": "Folder 2",
      "permalink": "https://app.smartsheet.com/b/home?lx=xgDVrNNbi-O9XwINEpT5Er"
        }
    ]
}

GET /home/folders

Gets a list of the top-level child folders within the user's Sheets folder (Home).

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Folder objects, limited to the following attributes: id name permalink
Access Scope	READ_SHEETS

List Folders (Subfolder)

Example request: list folders (subfolder)

curl https://api.smartsheet.com/2.0/folders/{folderId}/folders \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"

// Set options
var options = {
  folderId: 5107651446105988
};

// List folders in another folder
smartsheet.folders.listChildFolders(options)
  .then(function(folderList) {
    console.log(folderList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Folder> folders = smartsheet.FolderResources.ListFolders(
  5107651446105988,           // long folderId
  null                        // PaginationParameters
);

// Omit pagination parameters
PagedResult<Folder> folders = smartsheet.folderResources().listFolders(
  510765144610598L,               // long parentFolderId
  null                             // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Folders.list_folders(
  5107651446105988,       # folder_id
  include_all=True)
folders = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Folders.list_folders(
  5107651446105988,       # folder_id
  page_size=5,
  page=1)
pages = response.total_pages
folders = response.data

response = smartsheet.folders.list_in_folder(
  folder_id: 5107651446105988
)
folders = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": 9116888184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 225255547361668,
            "name": "Folder 2",
      "permalink": "https://app.smartsheet.com/b/home?lx=xgDVrNNbi-O9XwINEpT5Er"
        }
    ]
}

GET /folders/{folderId}/folders

Gets a list of the top-level child folders within the specified folder.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Folder objects, limited to the following attributes: id name permalink
Access Scope	READ_SHEETS

List Folders (Workspace)

Example request: list folders (workspace)

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/folders \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"

// Set options
var options = {
  workspaceId: 1656220827314052
};

// List folders in workspace
smartsheet.workspaces.listWorkspaceFolders(options)
  .then(function(folderList) {
    console.log(folderList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Folder> folders = smartsheet.WorkspaceResources.FolderResources.ListFolders(
  1656220827314052,               // long workspaceId
  null                            // PaginationParameters
);

// Omit pagination parameters
PagedResult<Folder> folders = smartsheet.workspaceResources().folderResources().listFolders(
  1656220827314052L,                   // long workspaceId
  null                                 // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Workspaces.list_folders(
  1656220827314052,       # workspace_id
  include_all=True)
folders = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Workspaces.list_folders(
  1656220827314052,       # workspace_id
  page_size=5,
  page=1)
pages = response.total_pages
folders = response.data

response = smartsheet.folders.list_in_workspace(
  workspace_id: 1656220827314052
)
folders = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": 9116888184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 225255547361668,
            "name": "Folder 2",
      "permalink": "https://app.smartsheet.com/b/home?lx=xgDVrNNbi-O9XwINEpT5Er"
        }
    ]
}

GET /workspaces/{workspaceId}/folders

Gets a list of the top-level child folders within the specified workspace.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Folder objects, limited to the following attributes: id name permalink
Access Scope	READ_SHEETS

Move Folder

Example request: move folder

curl https://api.smartsheet.com/2.0/folders/{folderId}/move \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-d '{ 
  "destinationType": "folder", 
  "destinationId": 7960873114331012 
}' \
-X POST

// Set destination information
var body = {
  destinationType: "folder",
  destinationId: 7960873114331012
};

// Set options
var options = {
  folderId: 4509918431602564,
  body: body
};

// Move folder
smartsheet.folders.moveFolder(options)
  .then(function(folder) {
    console.log(folder);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination {
  DestinationId = 7960873114331012,       // long destinationFolderId
  DestinationType = DestinationType.FOLDER,
};

// Move folder
Folder folder = smartsheet.FolderResources.MoveFolder(
  4509918431602564,               // long folderId
  destination
);

// Specify destination
ContainerDestination destination = new ContainerDestination()
  .setDestinationType(DestinationType.FOLDER)
  .setDestinationId(7960873114331012L);

// Move folder
Folder folder = smartsheet.folderResources().moveFolder(
  4509918431602564L,                         // long folderId
  destination
);

folder = smartsheet_client.Folders.move_folder(
  4509918431602564,                           # folder_id to be moved
  smartsheet.models.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 = smartsheet_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 = smartsheet_client.Groups.create_group(
  smartsheet.models.Group({
    'name': 'API-created Group',
    'description': 'Group created via API',
    'members': smartsheet.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 account 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
);

smartsheet_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 = smartsheet_client.Groups.get_group(
  6932724448552836)       # group_id
# group is an instance of smartsheet.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 information about and an array of members for 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 = smartsheet_client.Groups.list_groups(include_all=True)
groups = response.data

# Sample 2: Paginate the list
response = smartsheet_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 account. 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 = smartsheet_client.Groups.update_group(
  2331373580117892,       # group_id
  smartsheet.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 account 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 = smartsheet_client.Groups.add_members(
  7917992160847748,       # group_id
  [smartsheet.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
);

smartsheet_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 = smartsheet_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 report, sheet, Sight (aka dashboard), or template, if any
	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

Related Items

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 = smartsheet_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 = smartsheet_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 = smartsheet_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": [],
  "scope": {
    "sheets": [],
    "workspaces": []
  }
}

Extends the Sheet object, adding the following:

scope	Scope	A report's scope can be defined as the sheet ids and workspace ids that make up the report.
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 account. 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.

Scope Object

Example: Scope object

"scope": {
  "sheets": [
    {
      "id": 4583173393803140,
    },
    {
      "id": 2331373580117892,
    }
  ],
  "workspaces": [
    {
      "id": 5709073300645764
    }
  ]
}

sheets	Sheet[]	Array of Sheet objects (containing just the sheet ID) of any sheets that the requestor has access to that make up the report
workspaces	Workspace[]	Array of Workspace objects (containing just the workspace ID) that the requestor has access to that make up the report

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 = smartsheet_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 scope -- adds the report's scope to the response source -- adds the Source object indicating which report the report was created from, if any 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
smartsheet_client.Reports.get_report_as_excel(
  3882962191181700,       # report_id
  download_folder_path
)

# Sample 2: Specify custom filename for the downloaded file
smartsheet_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
smartsheet_client.Reports.get_report_as_csv(
  3882962191181700,       # report_id
  download_folder_path
)

# Sample 2: Specify custom filename for the downloaded file
smartsheet_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 = smartsheet_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": [
    {   
      "id": 6761305928427396,
      "name": "r1",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=zWThapjNSR8LxW_kTdxPhQ"
    },  
    {   
      "id": 4508956358928260,
      "name": "r2",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=33-Y5QkQw6ZNSoApMKntbw"
    }   
  ]   
}

GET /reports

Gets a list of all reports that the user has access to in alphabetical order by name. The list contains an abbreviated Report object for each report.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	modifiedSince (optional): when specified with a date and time value, response only includes the objects that are modified on or after the date and time specified. If you need to keep track of frequent changes, it may be more useful to use Get Sheet Version.
Returns	IndexResult object containing an array of Report objects limited to the following attributes: id accessLevel name permalink
Access Scope	READ_SHEETS

Publish Report

Get Report Publish Status

Example request: get report publish status

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

// Set options
var options = {
  reportId: 3901932860401540
};

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

// [todo]

// [todo]

status = smartsheet_client.Reports.get_publish_status(
  1653067851556740)       # report_id

status = smartsheet.reports.get_publish_status(
  report_id: 4583173393803140
)

Example response

{
  "readOnlyFullEnabled": true,
  "readOnlyFullAccessibleBy": "ALL",
  "readOnlyFullUrl": "https://publish.smartsheet.com/6d35fa6c99334d4892f9591cf6065"
}

GET /reports/{reportId}/publish

Gets the Report's 'Publish' settings.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	ReportPublish object
Access Scope	READ_SHEETS

Set Report Publish Status

Example request: set report publish status

curl https://api.smartsheet.com/2.0/reports/{reportId}/publish \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"readOnlyFullEnabled": true, "readOnlyFullAccessibleBy": "ORG"}'

// Set options
var options = {
  reportId: 1653087851556740,
  body: {
    readOnlyFullEnabled: true,
    readOnlyFullAccessibleBy: "ALL"
  }
};

// Set report publish status
smartsheet.reports.setReportPublishStatus(options)
  .then(function(status) {
    console.log(status);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// [todo]

response = smartsheet_client.Reports.set_publish_status(
  1653067851556740,       # report_id
  smartsheet.models.ReportPublish({
    'read_only_full_enabled': True
  })
)

# Set options
body = {
  read_only_full_enabled: true,
  read_only_full_accessible_by: 'ORG'
}

# Set report publish status
status = smartsheet.reports.set_publish_status(
  report_id: 4583173393803140,
  body: body
)

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "readOnlyFullEnabled": true,
  "readOnlyFullAccessibleBy": "ORG",
    "readOnlyFullUrl": "http://publish.smartsheet.com/9862638d9c444014b5d7a114d436e99d"
  }
}

PUT /reports/{reportId}/publish

Sets the publish status of the report and returns the new status, including the URL of any enabled publishing.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	ReportPublish object
Returns	Result object containing a ReportPublish object
Access Scope	ADMIN_SHEETS

Send Report via Email

Example request: send report

curl https://api.smartsheet.com/2.0/reports/{reportId}/emails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here are the rows I mentioned in our meeting", "ccMe": false, "format": "PDF", "formatDetails": {"paperSize": "A4"}}'

// Configure email
var email = {
  "sendTo": [
    {
      "email": "john.doe@smartsheet.com"
    },
    {
      "groupId": 2258118617917316
    }
  ],
  "subject": "Check these rows out!",
  "message": "Here are the rows I mentioned in our meeting",
  "ccMe": false,
  "format": "PDF",
  "formatDetails": {
    "paperSize": "A4"
  }
};

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

// Send report via email
smartsheet.reports.sendReportViaEmail(options)
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify recipients
Recipient[] recipientSpecification = new Recipient[] {
  new Recipient { Email = "john.doe@smartsheet.com" },
  new Recipient { GroupId = 2258118617917316 }
};

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

// Send report via email
smartsheet.ReportResources.SendReport (8130994621441924, sheetEmail);       // long reportId

// Specify an individual recipient
RecipientEmail recipientEmail = new RecipientEmail()
  .setEmail("john.doe@smartsheet.com");

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

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

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

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

// Send report via email
smartsheet.reportResources().sendReport(
  8130994621441924L,      // long reportId
  emailSpecification
);

response = ss_client.Reports.send_report(
  8130994621441924,       # report_id
  ss_client.models.SheetEmail({
    'send_to': ss_client.models.Recipient({
      'email': 'john.doe@smartsheet.com'
    }),
    'subject': 'Check this report out!',
    'message': 'Here is the report I mentioned in our meeting.',
    'cc_me': False,
    'format': 'PDF',
    'format_details': ss_client.models.FormatDetails({
      'paper_size': 'A4'
    })
  })
)

body = {
  send_to: [
    {
      email: 'john.doe@smartsheet.com'
    },
    {
      group_id: 3051008235464580
    }
  ],
  subject: 'Check out this report!',
  message: 'Here is the report I mentioned in our meeting',
  cc_me: false,
  format: 'PDF',
  format_details: {
    paper_size: 'LEGAL'
  }
}

response = smartsheet.reports.send_via_email(
  report_id: 4583173393803140,
  body: body
)

Example response

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

POST /reports/{reportId}/emails

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	SheetEmail object
Returns	Result object
Access Scope	SHARE_SHEETS

Share Report

For details about report sharing, see Report Sharing.

Related Items

A report is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

Report Attachments

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

Report Cells

For details about working with a report's cells, see Cells.

Report Columns

For details about working with a report's columns, see Columns.

Report Discussions

For details about working with a report's discussions, see Discussions.

Report Rows

For details about working with a report's rows, see Rows.

Rows

A row is a component of a sheet or report. Each row is composed of a collection of cells, and may optionally contain discussions or attachments.

Objects

Row Object

Example: Row object

{
  "id": 2361756178769796,
  "sheetId": 4583173393803140,
  "rowNumber": 2,
  "parentId": 4392908622194564,
  "version": 23,
  "expanded": true,
  "accessLevel": "OWNER",
  "createdAt": "2017-10-06T21:21:25Z",
  "modifiedAt": "2018-03-22T21:24:50Z",
  "cells": []
}

id	number	Row Id
sheetId	number	Parent sheet Id
accessLevel	string	User's permission level on the sheet that contains the row
attachments	Attachment[]	Array of Attachment objects. Only returned if the include query string parameter contains attachments.
cells	Cell[]	Array of Cell objects belonging to the row
columns	Column[]	Array of Column objects. Only returned if the Get Row include query string parameter contains columns.
conditionalFormat	string	Describes this row's conditional format (see Formatting) Only returned if the include query string parameter contains format and this row has a conditional format applied.
createdAt	timestamp	Time of creation
createdBy	User	User object containing name and email of the creator of this row
discussions	Discussion[]	Array of Discussion objects. Only returned if the include query string parameter contains discussions.
expanded	Boolean	Indicates whether the row is expanded or collapsed
filteredOut	Boolean	true if this row is filtered out by a column filter (and thus is not displayed in the Smartsheet app), false if the row is not filtered out. Only returned if the include query string parameter contains filters.
format	string	Format descriptor (see Formatting). Only returned if the include query string parameter contains format and this row has a non-default format applied.
inCriticalPath	Boolean	Only returned, with a value of true, if the sheet is a project sheet with dependencies enabled and this row is in the critical path
locked	Boolean	Indicates whether the row is locked. In a response, a value of true indicates that the row has been locked by the sheet owner or the admin.
lockedForUser	Boolean	Indicates whether the row is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.
modifiedAt	timestamp	Time of last modification
modifiedBy	User	User object containing name and email of the last person to modify this row
permalink	string	URL that represents a direct link to the row in Smartsheet Only returned if the include query string parameter contains rowPermalink.
rowNumber	number	Row number within the sheet (1-based - starts at 1)
version	number	Sheet version number that is incremented every time a sheet is modified

Row Object Location-specifier Attributes

For more information, see Specify Row Location.

parentId	number	In a response - the Id of the parent row (if any). In a request - the Id of the desired parent row (used to specify the location for a new or moved row).
siblingId	number	In a response - the Id of the previous sibling row at the same hierarchical level of this row (if any). In a request - the Id of the desired sibling row (used to specify the location for a new or moved row).
above	Boolean	Specifies the location for a new or moved row. You can specify this attribute in a request, but it is never present in a response.
indent	number	Specifies the number of levels to indent an existing row. You can specify this attribute in a request, but it is never present in a response.
outdent	number	Specifies the number of levels to outdent an existing row. You can specify this attribute in a request, but it is never present in a response.
toBottom	Boolean	Adds or moves the row to the bottom of the sheet. You can specify this attribute in a request, but it is never present in a response.
toTop	Boolean	Adds or moves the row to the top of the sheet. You can specify this attribute in a request, but it is never present in a response.

CopyOrMoveRowDirective Object

rowIds	number[]	The Ids of the rows to move or copy from the source sheet
to	CopyOrMoveRowDestination	A CopyOrMoveRowDestination object that identifies the destination sheet

CopyOrMoveRowDestination Object

sheetId	number	Id of the destination sheet

CopyOrMoveRowResult Object

destinationSheetId	number	Id of the destination sheet
rowMappings	RowMapping[]	Array of RowMapping objects

RowMapping Object

from	number	Row Id in the source sheet
to	number	Row Id in the destination sheet

Add Rows

Example request: add rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"toTop":true, "cells": [ {"columnId": 7960873114331012, "value": true}, {"columnId": 642523719853956, "value": "New status", "strict": false} ] }, {"toTop":true, "cells": [ {"columnId": 7960873114331012, "value": true}, {"columnId": 642523719853956, "value": "New status", "strict": false} ] }]'

// Specify rows
var row = [
  {
    "toTop": true,
    "cells": [
      {
        "columnId": 7960873114331012,
        "value": true
      },
      {
        "columnId": 642523719853956,
        "value": "New status",
        "strict": false
      }
    ]
  },
  {
    "toTop": true,
    "cells": [
      {
        "columnId": 7960873114331012,
        "value": true
      },
      {
        "columnId": 642523719853956,
        "value": "New status",
        "strict": false
      }
    ]
  }
];

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

// Add rows to sheet
smartsheet.sheets.addRows(options)
  .then(function(newRows) {
    console.log(newRows);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify cell values for first row
Cell[] cellsA = new Cell[] {
  new Cell
  {
    ColumnId = 7960873114331012,
    Value = true
  },
  new Cell
  {
    ColumnId = 642523719853956,
    Value = "New status"
  }
};

// Specify contents of first row
Row rowA = new Row
{
  ToTop = true,
  Cells = cellsA
};

// Specify cell values of second row
Cell[] cellsB = new Cell[] {
  new Cell
  {
    ColumnId = 7960873114331012,
    Value = true
  },
  new Cell
  {
    ColumnId = 642523719853956,
    Value = "New status"
  }
};

// Specify contents of second row
Row rowB = new Row
{
  ToTop = true,
  Cells = cellsB
};

// Add rows to sheet
IList<Row> newRows = smartsheet.SheetResources.RowResources.AddRows(
  2331373580117892,               // long sheetId
  new Row[] { rowA, rowB }        // IEnumerable<Row> rowsToAdd
);

// Specify cell values for first row
List<Cell> rowACells = Arrays.asList(
  new Cell(7960873114331012L)   // column Id
    .setValue(true),
  new Cell(642523719853956L)    // column Id
    .setValue("New status")
);

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

// Specify cell values for second row
List<Cell> rowBCells = Arrays.asList(
  new Cell(7960873114331012L)
    .setValue(true),
  new Cell(642523719853956L)
    .setValue("New status")
);

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

// Add rows to sheet
List<Row> newRows = smartsheet.sheetResources().rowResources().addRows(
  1639534409607044L,    // sheet Id
  Arrays.asList(rowA, rowB));

# Specify cell values for one row
row_a = smartsheet.models.Row()
row_a.to_top = True
row_a.cells.append({
  'column_id': 7960873114331012,
  'value': True
})
row_a.cells.append({
  'column_id': 642523719853956
  'value': 'New Status',
  'strict': False
})

# Specify cell values for another row
row_b = smartsheet.models.Row()
row_b.to_top = True
row_b.cells.append({
  'column_id': 7960873114331012,
  'value': True
})
row_b.cells.append({
  'column_id': 642523719853956
  'value': 'New Status',
  'strict': False
})

# Add rows to sheet
response = smartsheet_client.Sheets.add_rows(
  2331373580117892,       # sheet_id
  [row_a, row_b])

# Specify values
body = {
  to_bottom: true,
  cells: [
    {
      column_id: 495660408563588,
      value: 'New Status'
    }
  ],
  locked: false
}

# Add rows to a sheet
response = smartsheet.sheets.rows.add(
  sheet_id: 2331373580117892,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
    "id": 7670198317672324,
    "sheetId": 2331373580117892,
    "rowNumber": 1,
    "expanded": true,
    "createdAt": "2013-02-28T17:45:13-08:00",
    "modifiedAt": "2013-02-28T17:45:13-08:00",
    "cells": [{
      "columnId": 7960873114331012,
      "type": "CHECKBOX",
      "value": true
      },
      {
      "columnId": 642523719853956,
      "displayValue": "New status",
      "type": "TEXT_NUMBER",
      "value": "New status"
      }
      ]
    },
    {
      "id": 2040698783459204,
      "sheetId": 2331373580117892,
      "rowNumber": 2,
      "expanded": true,
      "createdAt": "2013-02-28T17:45:13-08:00",
      "modifiedAt": "2013-02-28T17:45:13-08:00",
      "cells": [{
        "columnId": 7960873114331012,
        "type": "CHECKBOX",
        "value": true
        },
        {
        "columnId": 642523719853956,
        "displayValue": "New status",
        "type": "TEXT_NUMBER",
        "value": "New status"
        }
      ]
    }
  ],
  "version": 14
}

POST /sheets/{sheetId}/rows

Inserts one or more rows into the sheet specified in the URL. If you want to insert the rows in any position but the default, use location-specifier attributes.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	allowPartialSuccess (optional): when specified with a value of true, enables partial success for this bulk operation. See Partial Success for more information. 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	Row object or an array of Row objects, with the following attributes: One or more location-specifier attributes (optional) expanded (optional) format (optional) cells (optional) -- if specified, must be an array of Cell objects, where each object is limited to the following attributes: columnId (required) One of the following (required): formula: for cross-sheet formulas, you must first define a cross-sheet reference value When value is specified hyperlink (optional) with exactly one of the following attributes set: reportId sheetId url linkInFromCell (optional) with all of the following attributes set: columnId rowId sheetId strict (optional) format (optional) image (optional) -- if specified, use to update alternate text where altText = string. overrideValidation (optional) locked (optional) - true to lock the row or false to unlock the row. See Column Types for more information. NOTE: Column Ids must be valid for the sheet to which the row belongs, and must only be used once for each row in the operation. Cells of a project sheet in the "Finish Date" column cannot be updated via API. Cells of a project sheet in the "Start Date" column cannot be updated via API for rows that contain a value in the "Predecessor" column. Max length for a cell value is 4000 characters after which truncation occurs without warning. Empty string values are converted to null. 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".
Returns	Result object containing the newly created rows -- either a single Row object or array of Row objects, corresponding to what was specified in the request, as well as the new version of the sheet.
Errors	When allowPartialSuccess=false (or not specified): If an error occurs, the Error object returned contains a detail attribute set to an object with the following attribute: index: the array index of the row that caused the error (0 if a single Row was passed in) If any error occurs, the entire request fails (no rows are added), and the error response returned describes the first problem that was encountered. For example: {   "errorCode": 1042,   "message": "The cell value in column 5504245941200772 did not conform to the strict requirements for type CHECKBOX."   "detail": {     "index": 4   } } When allowPartialSuccess=true: 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.
Access Scope	WRITE_SHEETS

Copy Rows to Another Sheet

Example request: copy rows to another sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/copy \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "rowIds": [145417762563972, 8026717110462340], "to": {"sheetId": 2258256056870788} }'

// Specify the directive
var copyRow = {
  "rowIds": [145417762563972,8026717110462340],
  "to": {
    "sheetId": 2258256056870788
  }
};

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

// Copy rows
smartsheet.sheets.copyRowToAnotherSheet(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination sheet
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination { SheetId = 2258256056870788 };

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

// Sample 1: Omit 'include' and 'ignoreRowsNotFound' parameters
CopyOrMoveRowResult results = smartsheet.SheetResources.RowResources.CopyRowsToAnotherSheet(
  4583173393803140,           // long sheetId
  directive,
  null,                       // IEnumerable<CopyRowInclusion> include
  null                        // Nullable<bool> ignoreRowsNotFound
);

// Sample 2: Specify 'include' parameter with value of "CHILDREN", and 'ignoreRowsNotFound' parameter with value of 'true'
CopyOrMoveRowResult results = smartsheet.SheetResources.RowResources.CopyRowsToAnotherSheet(
  4583173393803140,           // long sheetId
  directive,
  new CopyRowInclusion[] {
    CopyRowInclusion.CHILDREN },
  true
);

// Specify destination sheet
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination()
  .setSheetId(2258256056870788L);

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

// Sample 1: Omit 'include' and 'ignoreRowsNotFound' parameters
CopyOrMoveRowResult results = smartsheet.sheetResources().rowResources().copyRows(
  4583173393803140L,                        // long sheetId
  null,                                     // EnumSet<RowCopyInclusion> includes
  true,                                     // Boolean ignoreRowsNotFound
  directive
);

// Sample 2: Specify 'include' parameter with value of "CHILDREN", and 'ignoreRowsNotFound' parameter with value of 'true'
CopyOrMoveRowResult results = smartsheet.sheetResources().rowResources().copyRows(
  4583173393803140L,                        // long sheetId
  EnumSet.of(RowCopyInclusion.CHILDREN),
  true,
  directive
);

response = smartsheet_client.Sheets.copy_rows(
  4583173393803140,               # sheet_id of rows to be copied
  smartsheet.models.CopyOrMoveRowDirective({
    'row_ids': [145417762563972, 8026717110462340],
    'to': smartsheet.models.CopyOrMoveRowDestination({
      'sheet_id': 2258256056870788
    })
  })
)

# Specify rows to copy and destination sheet
body = {
  row_ids: [
    145417762563972,
    8026717110462340
  ],
  to: {
    sheet_id: 2258256056870788
  }
}

# Copy rows to another sheet
response = smartsheet.sheets.rows.copy_to_another_sheet(
  sheet_id: 4583173393803140,
  body: body
)

Example response

{
  "destinationSheetId": 2258256056870788,
  "rowMappings": [
    {    
      "from": 145417762563972,
      "to": 4508365800925060
    },   
    {    
      "from": 8026717110462340,
      "to": 2256565987239812
    }    
  ]    
}

POST /sheets/{sheetId}/rows/copy

Copies rows from the sheet specified in the URL to (the bottom of) another sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of row elements to copy in addition to the cell data: all - specify a value of all to include everything (attachments, children, and discussions) attachments children - if specified, any child rows of the rows specified in the request are also copied to the destination sheet, and parent-child relationships amongst rows are preserved within the destination sheet; if not specified, only the rows specified in the request are copied. discussions ignoreRowsNotFound (optional) -- true or false: default is false. If set to true, specifying row Ids that do not exist within the source sheet does not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet causes an error response (and no rows are copied).
Request Body	CopyOrMoveRowDirective object
Returns	CopyOrMoveRowResult object
Access Scope	WRITE_SHEETS

Delete Rows

Example request: delete rows

curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows?ids={rowId1},{rowId2},{rowId3}&ignoreRowsNotFound=true' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

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

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

// Specify 'ignoreRowsNotFound' parameter with value of 'true'
smartsheet.SheetResources.RowResources.DeleteRows(
  2252168947361668,                                    // long sheetId
  new long[] { 207098194749316, 207098194749317 },     // rowIds
  true                                                 // Boolean ignoreRowsNotFound
);

// Specify 'ignoreRowsNotFound' parameter with value of 'true'
smartsheet.sheetResources().rowResources().deleteRows(
  2252168947361668L,               // long sheetId
  new HashSet(Arrays.asList(
    207098194749316L,            // long rowId,
    207098194749317L,            // long additional rowId
    207098194749318L,)           // long additional rowId
  true                             // Boolean ignoreRowsNotFound
);

smartsheet_client.Sheets.delete_rows(
  2252168947361668,                       # sheet_id
  [207098194749316, 207098194749317])     # row_ids

smartsheet.sheets.rows.delete(
  sheet_id: 2252168947361668,
  row_ids: [207098194749316, 207098194749316]
)

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": [
    207098194749316,
    207098194749316
  ]
}

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

Deletes one or more rows from the sheet specified in the URL.

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

Get Row

Example request: get row

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

// Set options
var options = {
  sheetId: 4583173393803140,
  rowId: 2361756178769796
};

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

// Omit 'include' parameter and pagination parameters
Row row = smartsheet.SheetResources.RowResources.GetRow(
  4583173393803140,               // long sheetId
  2361756178769796,               // long rowId
  null,                           // IEnumerable<RowInclusion> include
  null                            // IEnumerable<RowExclusion> exclude
);

// Specify 'include' parameter with values of "COLUMNS" and "COLUMN_TYPE", and 'exclude' parameter with value of "NONEXISTENT_CELLS"
Row row = smartsheet.SheetResources.RowResources.GetRow(
  4583173393803140,               // long sheetId
  2361756178769796,               // long rowId
  new RowInclusion[] {
    RowInclusion.COLUMNS,
    RowInclusion.COLUMN_TYPE },
  new ObjectExclusion[] { ObjectExclusion.NONEXISTENT_CELLS }
);

// Sample 1: Omit 'include' parameter and pagination parameters
Row row = smartsheet.sheetResources().rowResources().getRow(
  4583173393803140L,       // long sheetId
  2361756178769796L,       // long rowId
  null,                    // EnumSet<RowInclusion> includes
  null                     // EnumSet<ObjectExclusion> excludes
);

// Sample 2: Specify 'include' parameter with values of "COLUMNS" and "COLUMN_TYPE", and 'exclude' parameter with value of "NONEXISTENT_CELLS"
Row row = smartsheet.sheetResources().rowResources().getRow(
  4583173393803140L,       // long sheetId
  2361756178769796L,       // long rowId
  EnumSet.of(
    RowInclusion.COLUMNS,
    RowInclusion.COLUMN_TYPE),
  EnumSet.of(
    ObjectExclusion.NONEXISTENT_CELLS)
);

# Include discussions, attachments, columns, and columnType
row = smartsheet_client.Sheets.get_row(
  4583173393803140,       # sheet_id 
  2361756178769796,       # row_id 
  include='discussions,attachments,columns,columnType'
)

row = smartsheet.sheets.rows.get(
  sheet_id: 4583173393803140,
  row_id: 2361756178769796
)

Example response

{
  "id": 2361756178769796,
  "sheetId": 4583173393803140,
  "rowNumber": 1,
  "expanded": true,
  "cells": [
    {
      "columnType": "TEXT_NUMBER",
      "value": "Revision 1",
      "displayValue": "Revision 1",
      "columnId": 4583173393803140
    },
    {
      "columnType": "PICKLIST",
      "value": "completed",
      "displayValue": "completed",
      "columnId": 2331373580117892
    }
  ],
  "createdAt": "2012-07-24T23:10:55-07:00",
  "modifiedAt": "2012-07-24T23:14:27-07:00"
}

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

Gets the row specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of elements to include in the response. See Row Include Flags. Also supports the columns include flag, which adds a columns array that specifies all of the columns for the sheet. This enables you to have the full context of the cells in the row. The filters include flag returns a filteredOut attribute indicating if the row should be displayed or hidden according to the sheet's filters.
	exclude (optional) -- a comma-separated list of elements to not include in the response. include=format&exclude=nonexistentCells: excludes cells that have never contained data yet returns those cells if they have formatting or conditional formatting 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 nonexistentCells: excludes cells that have never contained any data
Returns	Row object populated according to the specified parameters
Access Scope	READ_SHEETS

List Rows

To get the list of all rows in a sheet, use the Get Sheet operation.

Move Rows to Another Sheet

Example request: move rows to another sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/move \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "rowIds": [145417762563972, 8026717110462340], "to": {"sheetId": 2258256056870788} }'

// Specify the directive
var moveRow = {
  "rowIds": [145417762563972,8026717110462340],
  "to": {
    "sheetId": 2258256056870788
  }
};

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

// Move rows
smartsheet.sheets.moveRowToAnotherSheet(options)
  .then(function(movedRow) {
    console.log(movedRow);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination sheet
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination { SheetId = 2258256056870788 };

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

// Sample 1: Omit 'include' and 'ignoreRowsNotFound' parameters
CopyOrMoveRowResult results = smartsheet.SheetResources.RowResources.MoveRowsToAnotherSheet(
  4583173393803140,               // long sheetId
  directive,
  null,                           // IEnumerable<MoveRowInclusion> include
  null                            // Nullable<bool> ignoreRowsNotFound
);

// Sample 2: Specify 'include' parameter with value of "ATTACHMENTS" and "DISCUSSIONS", and 'ignoreRowsNotFound' parameter with value of 'true'
CopyOrMoveRowResult results = smartsheet.SheetResources.RowResources.MoveRowsToAnotherSheet(
  4583173393803140,               // long sheetId
  directive,
  new MoveRowInclusion[] {
    MoveRowInclusion.ATTACHMENTS,
    MoveRowInclusion.DISCUSSIONS },
  true                            // Nullable<bool> ignoreRowsNotFound
);

// Specify destination sheet
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination()
  .setSheetId(2258256056870788L);

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

// Sample 1: Omit 'include' and 'ignoreRowsNotFound' parameters
CopyOrMoveRowResult results = smartsheet.sheetResources().rowResources().moveRows(
  4583173393803140L,                  // long sheetId
  null,                               // EnumSet<RowMoveInclusion> includes
  true,                               // Boolean ignoreRowsNotFound
  directive
);

// Sample 2: Specify 'include' parameter with value of "ATTACHMENTS" and "DISCUSSIONS", and 'ignoreRowsNotFound' parameter with value of 'true'
CopyOrMoveRowResult results = smartsheet.sheetResources().rowResources().moveRows(
  4583173393803140L,                  // long sheetId
  EnumSet.of(
    RowMoveInclusion.ATTACHMENTS,
    RowMoveInclusion.DISCUSSIONS),
  true,                               // Boolean ignoreRowsNotFound
  directive
);

response = smartsheet_client.Sheets.move_rows(
  4583173393803140,           # sheet_id of rows to be moved
  smartsheet.models.CopyOrMoveRowDirective({
    'row_ids': [145417762563972, 8026717110462340],
    'to': smartsheet.models.CopyOrMoveRowDestination({
      'sheet_id': 2258256056870788
    })
  })
)

# Specify rows to move and destination sheet
body = {
  row_ids: [
    145417762563972,
    8026717110462340
  ],
  to: {
    sheet_id: 2258256056870788
  }
}

# Move rows to another sheet
response = smartsheet.sheets.rows.move_to_another_sheet(
  sheet_id: 4583173393803140,
  body: body
)

Example response

{
  "destinationSheetId": 2258256056870788,
  "rowMappings": [
    {    
      "from": 145417762563972,
      "to": 4508365800925060
    },   
    {    
      "from": 8026717110462340,
      "to": 2256565987239812
    }    
  ]    
}

POST /sheets/{sheetId}/rows/move

Moves rows from the sheet specified in the URL to (the bottom of) another sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of row elements to move in addition to the cell data: attachments discussions ignoreRowsNotFound (optional) -- true or false: default is false. If set to true, specifying row Ids that do not exist within the source sheet do not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet causes an error response (and no rows are moved).
Request Body	CopyOrMoveRowDirective object
Returns	CopyOrMoveRowResult object
Access Scope	WRITE_SHEETS

Send Rows via Email

Example request: send rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ 
  "sendTo": [ 
    {"email": "recipient@smartsheet.com"} 
  ], 
  "subject": "Check these rows out!", 
  "message": "Here are the rows I mentioned in our meeting", 
  "ccMe": false, 
  "rowIds": [ 
    6327127650920324, 3404239197235076 
  ], 
  "columnIds": [ 
    5190835902932868, 3791509922310020 
  ], 
  "includeAttachments": false, 
  "includeDiscussions": false 
} 

// Configure email
var email = {
  "sendTo": [
    {
      "email": "john.doe@smartsheet.com"
    },
    {
      "groupId": 2258118617917316
    }
  ],
  "subject": "Check these rows out!",
  "message": "Here are the rows I mentioned in our meeting",
  "ccMe": false,
  "includeDiscussions": false,
  "includeAttachments": true,
  "rowIds": [
    1049041315358596,
    5552640942729092
  ]
};

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

// Send row via email
smartsheet.sheets.sendRows(options)
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify recipients
Recipient[] recipients = new Recipient[] {
  new Recipient { Email = "recipient@smartsheet.com" }
};

// Configure email
MultiRowEmail multiRowEmail = new MultiRowEmail {
  SendTo = recipients,
  Subject = "some subject",
  Message = "some message",
  CcMe = false,
  RowIds = new long[] { 6327127650920324, 3404239197235076 },
  ColumnIds = new long[] { 5190835902932868, 3791509922310020 },
  IncludeAttachments = false,
  IncludeDiscussions = false
};

// Send rows via email
smartsheet.SheetResources.RowResources.SendRows(4293147074291588, multiRowEmail);       // sheetId

// Specify recipients
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder()
  .setEmail("recipient@smartsheet.com")
  .build();

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

// Configure email
MultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()
  .setSendTo(recipients)
  .setSubject("some subject")
  .setMessage("some message")
  .setCcMe(false)
  .setRowIds(Arrays.asList(6327127650920324L, 3404239197235076L)
  .setColumnIds(Arrays.asList(5190835902932868L, 3791509922310020L)
  .setIncludeAttachments(false)
  .setIncludeDiscussions(false)
  .build();

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

# Configure email
email = ss_client.models.MultiRowEmail()
email.send_to = ss_client.models.Recipient({
  'email': 'john.doe@smartsheet.com'
})
email.row_ids = [6327127650920324, 3404239197235076]
email.column_ids = [5190835902932868, 3791509922310020]

# Send rows via email
response = ss_client.Sheets.send_rows(
  4293147074291588,       # sheet_id
  email)

# Configure email
body = {
  row_ids: [
    409840559384452,
    2661640373069700
  ],
  column_ids: [
    495660408563588,
    2747460222248836
  ],
  send_to: [
    {
      email: 'john.doe@smartsheet.com'
    },
    {
      group_id: 3051008235464580
    }
  ],
  subject: 'Check these rows out!',
  message: 'Here are the rows I mentioned in our meeting',
  cc_me: false,
  include_attachments: false,
  include_discussions: true,
  layout: 'VERTICAL'
}

# Send rows
response = smartsheet.sheets.rows.send_via_email(
  sheet_id: 4583173393803140,
  body: body
)

Example response

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

POST /sheets/{sheetId}/rows/emails

Sends one or more rows via email.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	MultiRowEmail object. The columns included for each row in the email are populated according to the following rules: If the columnIds attribute of the MultiRowEmail object is specified as an array of column Ids, those specific columns are included. If the columnIds attribute of the MultiRowEmail object is omitted, all columns except hidden columns shall be included. If the columnIds attribute of the MultiRowEmail object is specified as empty, no columns shall be included. (NOTE: In this case, either includeAttachments=true or includeDiscussions=true must be specified.)
Returns	Result object
Access Scope	SHARE_SHEETS

Send Update Request

For details about sending update requests, see Create Update Request.

Sort Rows

For details about sorting the rows in a sheet, see Sort Rows in Sheet.

Specify Row Location

When you add a row, the default behavior is for Smartsheet to put the new row at the bottom of the sheet. And when you update a row, the default behavior is to keep the row where it is. It is not necessary to use a location-specifier attribute if you want the default behavior.

To specify a location for new or updated rows other than the defaults, use the table below for reference. The table details possible row locations and provides JSON examples to help you construct one or more Row objects with location-specifier attributes.

Note the following restrictions:

• Use only one location-specifier attribute per request, unless you use parentId and toBottom or siblingId and above.
  
• If you specify multiple rows in the request, all rows must have the same location-specifier attributes.
• If you specify the parentId attribute, you cannot also specify the siblingId attribute.
• If you specify the siblingId attribute, you cannot also specify the parentId, toTop, or toBottom attributes.
• If you want to indent or outdent multiple rows, use the parentId attribute.

Destination	Row Attributes	Examples
Top of a sheet	toTop	("toTop": true}
Bottom of a sheet	toBottom	("toBottom": true}
Top of an indented section a.k.a., first child row	parentId	("parentId": 8896508249565060}
Bottom of an indented section a.k.a., last child row	parentId + toBottom	{"parentId": 8896508249565060, "toBottom": true}
Below a specific row, at the same indent level	siblingId	{"siblingId": 8896508249565060}
Above a specific row, at the same indent level	siblingId + above	{"siblingId": 8896508249565060, "above": true}
Indent one existing row, must have a value of "1"	indent	{"indent": 1}
Outdent one existing row, must have a value of "1"	outdent	{"outdent": 1}

Update Rows

Example request: update rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '[{"id": "6572427401553796", "cells": [{"columnId": 7518312134403972,"image": {"altText": "New Alt Text"},"value": "new value"}, {"columnId": 1888812600190852,"value": "A"}]}, {"id": "2068827774183300", "cells": [{"columnId": 7518312134403972,"value": "desc_updated"}, {"columnId": 1888812600190852,"value": "B"}, {"columnId": 6552023773538180,"objectValue": {"objectType": "MULTI_CONTACT","values": [{"objectType": "CONTACT","email": "john.doe@smartsheet.com","name": "John Doe"}, {"objectType": "CONTACT","email": "jane.roe@smartsheet.com","name": "Jane Roe"}]}}]}]'

// Specify updated cell values
var row = [
  {
    "id": "6572427401553796",
    "cells": [
      {
        "columnId": 7518312134403972,
        "value": "new value"
      },
      {
        "columnId": 1888812600190852,
        "value": "A"
      }
    ]
  },
  {
    "id": "2068827774183300",
    "cells": [
      {
        "columnId": 7518312134403972,
        "value": "desc_updated"
      },
      {
        "columnId": 1888812600190852,
        "value": "B"
      }
    ]
  }
];

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

// Update rows in sheet
smartsheet.sheets.updateRow(options)
  .then(function(updatedRows) {
    console.log(updatedRows);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify updated value for first cell
var cellToUpdateA = new Cell
{
  ColumnId = 7518312134403972,
  Value = "new value"
};

// Specify updated value for second cell
var cellToUpdateB = new Cell
{
  ColumnId = 1888812600190852,
  Value = "A"
};

// Identify row and add new cell values to it
var rowToUpdate = new Row
{
  Id = 6572427401553796,
  Cells = new Cell[] { cellToUpdateA, cellToUpdateB }
};

IList<Row> updatedRow = smartsheet.SheetResources.RowResources.UpdateRows(
  2068827774183300,    // sheet Id
  new Row[] {rowToUpdate}
);

// Specify updated cell values for first row
Cell cellA = new Cell(7518312134403972L)   // column Id
  .setValue("new value");

Cell cellB = new Cell(6392412227561348L)   // column Id
  .setValue(123);

Row rowA = new Row(2068827774183300L);
rowA.setCells(Arrays.asList(cellA, cellB));

// Specify updated cell values for second row
Cell cellC = new Cell(7518312134403972L)
  .setValue("desc_updated");

Cell cellD = new Cell(6392412227561348L)
  .setValue(456);

Row rowB = new Row(6572427401553796L);
rowB.setCells(Arrays.asList(cellC, cellD));

// Update rows in sheet
List<Row> updatedRows = smartsheet.sheetResources().rowResources().updateRows(
  1639534409607044L,                      // long sheetId
  Arrays.asList(rowA, rowB)
);

# Build new cell value
new_cell = smartsheet.models.Cell()
new_cell.column_id = 7036894123976580
new_cell.value = "new value"
new_cell.strict = False

# Build the row to update
new_row = smartsheet.models.Row()
new_row.id = 6809535313667972
new_row.cells.append(new_cell)

# Update rows
updated_row = smartsheet_client.Sheets.update_rows(
  2068827774183300,      # sheet_id
  [new_row])

# Specify updated cell values
body = {
  id: 4293147074291588,   # row Id
  cells: [
    column_id: 7036894123976580,
    value: 'new value'
  ]
}

# Update row
response = smartsheet.sheets.rows.update(
  sheet_id: 2068827774183300,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
    "id": 2068827774183300,
    "rowNumber": 2,
    "parentRowNumber": 1,
    "parentId": 4624744004773764,
    "expanded": true,
    "createdAt": "2015-01-09T11:41:55-08:00",
    "modifiedAt": "2015-02-23T15:36:07-08:00",
    "cells": [{
      "columnId": 7518312134403972,
      "type": "TEXT_NUMBER",
      "value": "desc_updated",
      "displayValue": "desc_updated"
    },
    {
      "columnId": 1888812600190852,
      "type": "PICKLIST",
      "value": "B",
      "displayValue": "B"
    },
    {
      "columnId": 6392412227561348,
      "type": "TEXT_NUMBER",
      "value": 1,
      "displayValue": "1"
    }
    ]
  },
  {
    "id": 6572427401553796,
    "rowNumber": 3,
    "parentRowNumber": 1,
    "parentId": 4624744004773764,
    "expanded": true,
    "createdAt": "2015-01-09T11:41:55-08:00",
    "modifiedAt": "2015-02-23T15:36:07-08:00",
    "cells": [{
      "columnId": 7518312134403972,
      "type": "TEXT_NUMBER",
      "value": "new value",
      "displayValue": "new value"
    },
    {
      "columnId": 1888812600190852,
      "type": "PICKLIST",
      "value": "A",
      "displayValue": "A"
    },
    {
      "columnId": 6392412227561348,
      "type": "TEXT_NUMBER",
      "value": 1,
      "displayValue": "1"
    },
    {
      "columnId": 6552023773538180,
      "displayValue": "Jane Roe, John Doe"
    }
    ]
  }
  ],
  "version": 8
}

PUT /sheets/{sheetId}/rows

Updates cell values in the specified rows, expands/collapses the specified rows, and/or modifies the position of specified rows (including indenting/outdenting). For detailed information about changing row positions, see location-specifier attributes.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	allowPartialSuccess (optional): when specified with a value of true, enables partial success for this bulk operation. See Partial Success for more information. 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	Row object or an array of Row objects, with the following attributes: id (required) One or more location-specifier attributes (optional) expanded (optional) format (optional) cells (optional) -- if specified, must be an array of Cell objects, where each object is limited to the following attributes: columnId (required) One of the following (required): formula: for cross-sheet formulas, you must first define a cross-sheet reference value When value is specified hyperlink (optional) with exactly one of the following attributes set: reportId sheetId url linkInFromCell (optional) with all of the following attributes set: columnId rowId sheetId strict (optional) format (optional) image (optional) -- if specified, use to update alternate text where altText = string. overrideValidation (optional) locked (optional) - true to lock the row or false to unlock the row. See Column Types for more information. NOTE: Column Ids must be valid for the sheet to which the row belongs, and must only be used once for each row in the operation. Cells of a project sheet in the "Finish Date" column cannot be updated via API. Cells of a project sheet in the "Start Date" column cannot be updated via API for rows that contain a value in the "Predecessor" column. Max length for a cell value is 4000 characters after which truncation occurs without warning. Empty string values are converted to null. 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".
Returns	Result object containing an array of the updated rows.
Errors	When allowPartialSuccess=false (or not specified): If an error occurs, the Error object returned contains a detail attribute set to an object with the following attributes: index: the array index of the row that caused the error (0 if a single row was passed in) rowId: the id of the row that caused the error (omitted if the row was missing an Id) If any error occurs, the entire request fails (no rows are updated), and the error response returned describes the first problem that was encountered. For example: {   "errorCode": 1042,   "message": "The cell value in column 5504245941200772 did not conform to the strict requirements for type CHECKBOX."   "detail": {     "index": 4     "rowId": 6572427401553796   } } When allowPartialSuccess=true: 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.
Access Scope	WRITE_SHEETS

Related Items

A row is comprised of a collection of cells, and may optionally contain attachments and discussions.

Row Attachments

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

Row Cells

For details about working with a row's cells, see Cells.

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

Row Discussions

For details about working with a row's discussions, see Discussions.

Row Include Flags

Endpoints which return rows (for example, Get Sheet, Get Row) support the optional include query string parameter. If specified, the value of the include parameter is a comma-delimited list of flags that indicate additional attributes to be included in each Row object within the response.

Include Flag	Description
attachments	Includes row attachments array. To include discussion attachments, both attachments and discussions must be present in the include list.
columnType	Includes columnType attribute in the row's cells indicating the type of the column the cell resides in.
discussions	Includes row discussions array. To include discussion attachments, both attachments and discussions must be present in the include list.
filters	Includes filteredOut attribute indicating if the row should be displayed or hidden according to the sheet's filters.
format	Includes format attribute on the row, its cells, or summary fields. See Formatting.
objectValue	Includes objectValue attribute on cells containing values. For more information see Cell Reference.
rowPermalink	Includes permalink attribute that represents a direct link to the row in the Smartsheet application.
rowWriterInfo	DEPRECATED Includes createdBy and modifiedBy attributes on the row, indicating the row's creator, and last modifier.
summary	Includes SheetSummary object.
writerInfo	Includes createdBy and modifiedBy attributes on the row or summary fields, indicating the row or summary field's creator, and last modifier.

Search

Search a specific sheet or search across all sheets that a user can access.

Objects

SearchResult Object

Example: SearchResult object

{
  "results": [
    {
      "contextData": [
        "Discussion 1"
    ],
    "objectId": 1888207043356548,
    "objectType": "discussion",
    "parentObjectId": 7141187195824004,
    "parentObjectName": "Sheet 1",
    "parentObjectType": "sheet",
    "text": "discussion stuff goes here"
    }
  ],
  "totalCount": 2
}

results	SearchResultItem[]	Array of SearchResultItem objects
totalCount	number	Total number of search results

SearchResultItem Object

objectId	number	Search result object Id
parentObjectId	number	Search result parent object Id
contextData	array	Additional info on search result context (row num)
objectType	string	Search result object type (attachment, discussion, folder, report, row, sheet, Sight, summaryField, template, workspace)
parentObjectName	string	Search result parent object name
parentObjectType	string	Search result parent object type (folder, report, sheet, Sight, template, workspace)
text	string	Search result text excerpt

Search Everything

Example request: search everything

curl 'https://api.smartsheet.com/2.0/search?query=stuff' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  query: "stuff"
};

// Search everything
smartsheet.search.searchAll(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set search criteria
string query = "stuff";

// Search everything
SearchResult results = smartsheet.SearchResources.Search(query);

// Set search criteria
String query = "stuff";

// Search everything
SearchResult results = smartsheet.searchResources().search(query);

# Set search criteria
query = 'stuff'

# Search everything
result = smartsheet_client.Search.search(query)
# result is a smartsheet.models.SearchResult object

results = smartsheet.search.search_all(
  query: 'stuff'
)

Example response

{
  "results": [
    {
      "contextData": [
        "Discussion 1"
      ],
      "objectId": 1888207043356548,
      "objectType": "discussion",
      "parentObjectId": 7141187195824004,
      "parentObjectName": "Sheet 1",
      "parentObjectType": "sheet",
      "text": "discussion stuff goes here"
    },
    {
      "contextData": [
        "Row 1"
      ],
      "objectId": 2711817823774596,
      "objectType": "row",
      "parentObjectId": 2583735121012612,
      "parentObjectName": "Sheet 2",
      "parentObjectType": "sheet",
      "text": "row stuff goes here"
    }
  ],
  "totalCount": 2
}

GET /search

Searches all sheets that the user can access, for the specified text.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	query (required): text with which to perform the search. Enclose in double-quotes for an exact search.
	include (optional): when specified with a value of favoriteFlag, response indicates which returned items are favorites: favorite -- folders, reports, sheets, Sights, templates, and workspaces will have the property favorite: true parentObjectFavorite -- attachments, discussions, summary fields, and rows will have the property parentObjectFavorite: true
	location (optional): when specified with a value of personalWorkspace, limits the response to only those items in the user's workspaces.
	modifiedSince (optional): when specified with a date and time value, response only includes the objects that are modified on or after the date and time specified. If you need to keep track of frequent changes, it may be more useful to use Get Sheet Version.
	scopes (optional): If search fails, try using an array for each type of this comma-separated list of search filters: attachments cellData comments folderNames reportNames sheetNames sightNames summaryFields templateNames workspaceNames
Returns	SearchResult object that contains a maximum of 100 SearchResultems
Access Scope	READ_SHEETS

Search Sheet

Example request: search sheet

curl 'https://api.smartsheet.com/2.0/search/sheets/{sheetId}?query=stuff' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  sheetId: 1888207043356548,
  queryParameters: {
    query: "stuff"
  }
};

// Search sheet
smartsheet.search.searchSheet(options)
  .then(function (data) {
    console.log(data);
  })
  .catch(function (error) {
    console.log(error);
  });

// Set search criteria
string query = "stuff";

// Search sheet
SearchResult results = smartsheet.SearchResources.SearchSheet(
  9283173393803140,       // long sheetId
  query                   // string
);

// Set search criteria
string query = "stuff";

// Search sheet
SearchResult results = smartsheet.searchResources().searchSheet(
  9283173393803140L,       // long sheetId
  query
);

# Set search criteria
query = 'stuff'

# Search sheet
response = ss_client.Search.search_sheet(
  9283173393803140,       # sheet_id
  query)
# response is a ss_client.models.SearchResult object

response = smartsheet.search.search_sheet(
  query: 'stuff',
  sheet_id: 9283173393803140
)

Example response

{
  "results": [
    {
      "contextData": [
        "Discussion 1"
      ],
      "objectId": 1888207043356548,
      "objectType": "discussion",
      "parentObjectId": 7141187195824004,
      "parentObjectName": "Sheet 1",
      "parentObjectType": "sheet",
      "text": "discussion stuff goes here"
    }
  ],
  "totalCount": 1
}

GET /search/sheets/{sheetId}

Searches a sheet for the specified text.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	query (required): Text with which to perform the search. Use double-quotes for an exact search.
Returns	SearchResult object that contains a maximum of 100 SearchResultem objects
Access Scope	READ_SHEETS

Send via Email

Send a report, row, or sheet via email.

Objects

Example: Email object

{
    "sendTo": [{
        "email": "john.doe@smartsheet.com"
    }, {
        "groupId": 2258118617917316
    }],
    "subject": "Check these rows out!",
    "message": "Here are the rows I mentioned in our meeting",
    "ccMe": false,
    "format": "PDF",
    "formatDetails": {
        "paperSize": "A4"
    }
}

Email Object

ccMe	Boolean	Indicates whether to send a copy of the email to the sender.
message	string	The message of the email.
sendTo	Recipient[]	Array of Recipient objects.
subject	string	The subject of the email.

FormatDetails Object

paperSize	string	One of the following values: LETTER, LEGAL, WIDE, ARCHD, A4, A3, A2, A1, A0.

Recipient Object

Specifies the recipient of an Email. The recipient may be either an individual or a group. To specify an individual, set the email attribute; to specify a group, set the groupId attribute. Either email and groupId may be set, but not both.

groupId	number	The Id of a group recipient.
email	string	The email address of an individual recipient.

RowEmail Object

Extends the Email object, adding the following:

columnIds	number[]	Ids of the columns to be included.
includeAttachments	Boolean	Indicates whether to include attachments in the email.
includeDiscussions	Boolean	Indicates whether to include discussions in the email.
layout	string	One of the following values: HORIZONTAL, VERTICAL. Optional, defaults to HORIZONTAL when multiple rows are being sent, and to VERTICAL when a single row is being sent. HORIZONTAL formats the rows being sent as a grid, whereas VERTICAL formats the rows being sent as separate cards.

MultiRowEmail Object

Extends the RowEmail object, adding the following:

rowIds	number[]	Ids of rows to be included.

SheetEmail Object

Extends the Email object, adding the following:

format	string	One of the following values: EXCEL, PDF, or PDF_GANTT
formatDetails	FormatDetails	A FormatDetails object.

Send Report

Example request: send report

curl https://api.smartsheet.com/2.0/reports/{reportId}/emails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here are the rows I mentioned in our meeting", "ccMe": false, "format": "PDF", "formatDetails": {"paperSize": "A4"}}'

// Configure email
var email = {
  "sendTo": [
    {
      "email": "john.doe@smartsheet.com"
    },
    {
      "groupId": 2258118617917316
    }
  ],
  "subject": "Check these rows out!",
  "message": "Here are the rows I mentioned in our meeting",
  "ccMe": false,
  "format": "PDF",
  "formatDetails": {
    "paperSize": "A4"
  }
};

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

// Send report via email
smartsheet.reports.sendReportViaEmail(options)
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify recipients
Recipient[] recipientSpecification = new Recipient[] {
  new Recipient { Email = "john.doe@smartsheet.com" },
  new Recipient { GroupId = 2258118617917316 }
};

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

// Send report via email
smartsheet.ReportResources.SendReport (8130994621441924, sheetEmail);       // long reportId

// Specify an individual recipient
RecipientEmail recipientEmail = new RecipientEmail()
  .setEmail("john.doe@smartsheet.com");

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

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

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

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

// Send report via email
smartsheet.reportResources().sendReport(
  8130994621441924L,      // long reportId
  emailSpecification
);

response = ss_client.Reports.send_report(
  8130994621441924,       # report_id
  ss_client.models.SheetEmail({
    'send_to': ss_client.models.Recipient({
      'email': 'john.doe@smartsheet.com'
    }),
    'subject': 'Check this report out!',
    'message': 'Here is the report I mentioned in our meeting.',
    'cc_me': False,
    'format': 'PDF',
    'format_details': ss_client.models.FormatDetails({
      'paper_size': 'A4'
    })
  })
)

body = {
  send_to: [
    {
      email: 'john.doe@smartsheet.com'
    },
    {
      group_id: 3051008235464580
    }
  ],
  subject: 'Check out this report!',
  message: 'Here is the report I mentioned in our meeting',
  cc_me: false,
  format: 'PDF',
  format_details: {
    paper_size: 'LEGAL'
  }
}

response = smartsheet.reports.send_via_email(
  report_id: 4583173393803140,
  body: body
)

Example response

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

POST /reports/{reportId}/emails

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	SheetEmail object
Returns	Result object
Access Scope	SHARE_SHEETS

Send Rows

Example request: send rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ 
  "sendTo": [ 
    {"email": "recipient@smartsheet.com"} 
  ], 
  "subject": "Check these rows out!", 
  "message": "Here are the rows I mentioned in our meeting", 
  "ccMe": false, 
  "rowIds": [ 
    6327127650920324, 3404239197235076 
  ], 
  "columnIds": [ 
    5190835902932868, 3791509922310020 
  ], 
  "includeAttachments": false, 
  "includeDiscussions": false 
} 

// Configure email
var email = {
  "sendTo": [
    {
      "email": "john.doe@smartsheet.com"
    },
    {
      "groupId": 2258118617917316
    }
  ],
  "subject": "Check these rows out!",
  "message": "Here are the rows I mentioned in our meeting",
  "ccMe": false,
  "includeDiscussions": false,
  "includeAttachments": true,
  "rowIds": [
    1049041315358596,
    5552640942729092
  ]
};

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

// Send row via email
smartsheet.sheets.sendRows(options)
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify recipients
Recipient[] recipients = new Recipient[] {
  new Recipient { Email = "recipient@smartsheet.com" }
};

// Configure email
MultiRowEmail multiRowEmail = new MultiRowEmail {
  SendTo = recipients,
  Subject = "some subject",
  Message = "some message",
  CcMe = false,
  RowIds = new long[] { 6327127650920324, 3404239197235076 },
  ColumnIds = new long[] { 5190835902932868, 3791509922310020 },
  IncludeAttachments = false,
  IncludeDiscussions = false
};

// Send rows via email
smartsheet.SheetResources.RowResources.SendRows(4293147074291588, multiRowEmail);       // sheetId

// Specify recipients
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder()
  .setEmail("recipient@smartsheet.com")
  .build();

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

// Configure email
MultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()
  .setSendTo(recipients)
  .setSubject("some subject")
  .setMessage("some message")
  .setCcMe(false)
  .setRowIds(Arrays.asList(6327127650920324L, 3404239197235076L)
  .setColumnIds(Arrays.asList(5190835902932868L, 3791509922310020L)
  .setIncludeAttachments(false)
  .setIncludeDiscussions(false)
  .build();

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

# Configure email
email = ss_client.models.MultiRowEmail()
email.send_to = ss_client.models.Recipient({
  'email': 'john.doe@smartsheet.com'
})
email.row_ids = [6327127650920324, 3404239197235076]
email.column_ids = [5190835902932868, 3791509922310020]

# Send rows via email
response = ss_client.Sheets.send_rows(
  4293147074291588,       # sheet_id
  email)

# Configure email
body = {
  row_ids: [
    409840559384452,
    2661640373069700
  ],
  column_ids: [
    495660408563588,
    2747460222248836
  ],
  send_to: [
    {
      email: 'john.doe@smartsheet.com'
    },
    {
      group_id: 3051008235464580
    }
  ],
  subject: 'Check these rows out!',
  message: 'Here are the rows I mentioned in our meeting',
  cc_me: false,
  include_attachments: false,
  include_discussions: true,
  layout: 'VERTICAL'
}

# Send rows
response = smartsheet.sheets.rows.send_via_email(
  sheet_id: 4583173393803140,
  body: body
)

Example response

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

POST /sheets/{sheetId}/rows/emails

Sends one or more rows via email.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	MultiRowEmail object. The columns included for each row in the email are populated according to the following rules: If the columnIds attribute of the MultiRowEmail object is specified as an array of column Ids, those specific columns are included. If the columnIds attribute of the MultiRowEmail object is omitted, all columns except hidden columns shall be included. If the columnIds attribute of the MultiRowEmail object is specified as empty, no columns shall be included. (NOTE: In this case, either includeAttachments=true or includeDiscussions=true must be specified.)
Returns	Result object
Access Scope	SHARE_SHEETS

Send Sheet

Example request: send sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/emails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here is the Sheet I mentioned in our meeting.", "ccMe": false, "format": "PDF", "formatDetails": {"paperSize": "A4"}}'

// Configure email
var email = {
  "sendTo": [
    {
      "email": "john.doe@smartsheet.com"
    },
    {
      "groupId": 2258118617917316
    }
  ],
  "subject": "Check these rows out!",
  "message": "Here are the rows I mentioned in our meeting",
  "ccMe": false,
  "format": "PDF",
  "formatDetails": {
    "paperSize": "A4"
  }
};

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

// Send sheet via email
smartsheet.sheets.sendSheetViaEmail(options)
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify recipients
Recipient[] recipients = new Recipient[] {
  new Recipient { Email = "john.doe@smartsheet.com" },
  new Recipient { GroupId = 2258118617917316 }
};

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

// Send sheet via email
smartsheet.SheetResources.SendSheet(4293147074291588, sheetEmail);      // sheetId

// Specify individual recipient
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder()
  .setEmail("john.doe@smartsheet.com")
  .build();

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

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

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

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

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

response = ss_client.Sheets.send_sheet(
  4293147074291588,           # sheet_id
  ss_client.models.SheetEmail({
    'send_to': [
      ss_client.models.Recipient({'email': 'john.doe@smartsheet.com'}),
      ss_client.models.Recipient({'group_id': 2258118617917316})
    ],
    'subject': 'Check these rows out!',
    'message': 'Here are the rows I mentioned in our meeting.',
    'cc_me': False,
    'format': 'PDF',
    'format_details': ss_client.models.FormatDetails({
      'paper_size': 'A4'
    })
  })
)

# Configure email
body = {
  send_to: [
    {
      email: 'john.doe@smartsheet.com'
    },
    {
      group_id: 3051008235464580
    }
  ],
  subject: 'Check these rows out!',
  message: 'Here are the rows I mentioned in our meeting',
  cc_me: false,
  format: 'PDF',
  format_details: {
    paper_size: 'LEGAL'
  }
}

# Send sheet
response = smartsheet.sheets.send_via_email(
  sheet_id: 3294745817573252,
  body: body
)

Example response

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

POST /sheets/{sheetId}/emails

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	SheetEmail object
Returns	Result object
Access Scope	SHARE_SHEETS

Send Update Request

For details about sending update requests, see Create Update Request.

Server Information

For developer convenience, the Smartsheet API provides access to application constants.

Objects

ServerInfo Object

Example: ServerInfo object

{
    "supportedLocales": [],
    "featureInfo": {
        "symbolsVersion": 2
    },
    "formats": {
        "defaults": "0,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0",
        "fontFamily": [],
        "fontSize": [],
        "bold": [],
        "italic": [],
        "underline": [],
        "strikethrough": [],
        "horizontalAlign": [],
        "verticalAlign": [],
        "color": [],
        "currency": [],
        "decimalCount": [],
        "thousandsSeparator": [],
        "numberFormat": [],
        "textWrap": []
    }
}

formats	FormatTables	Definition of format tables that are used in column, row, and cell format property. For more information, see Formatting.
supportedLocales	array	Array of strings representing all Smartsheet-supported locales.

Get Server Info

Example request: get server info

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

smartsheet.server.getInfo()
  .then(function(serverInfo) {
    console.log(serverInfo);
  })
  .catch(function(error) {
    console.log(error);
  });

ServerInfo serverInfo = smartsheet.ServerInfoResources.GetServerInfo();

ServerInfo serverInfo = smartsheet.serverInfoResources().getServerInfo();

info = smartsheet_client.Server.server_info()

info = smartsheet.server_info.get

Example response: (truncated)

{
  "supportedLocales": [  ],
  "formats": {  }
}

GET /serverinfo

Gets application constants.

Headers	None required (may be called unauthenticated)
Returns	ServerInfo object
Access Scope	None required (may be called unauthenticated)

Sharing

Use the Sharing operations to control sharing of reports, sheets, Sights, and workspaces.

Objects

Share Object

Example: Share object

{
  "id": "AQAISF82FOeE",
  "type": "GROUP",
  "groupId": 2331373580117892,
  "name": "Group 1",
  "accessLevel": "ADMIN",
  "scope": "ITEM",
  "createdAt": "2016-02-17T22:24:09Z",
  "modifiedAt": "2016-02-17T22:24:09Z"
}

id	string	Share Id. NOTE: unlike other Smartsheet object Ids, this Id is an alphanumeric string.
groupId	number	Group Id if the share is a group share, else null.
userId	number	User Id if the share is a user share, else null.
type	string	The type of this share. One of the following values: USER or GROUP.
accessLevel	string	User or group's access level on shared object.
ccMe	Boolean	Indicates whether to send a copy of the email to the sharer of the sheet. You can specify this attribute in a request, but it is never present in a response.
createdAt	timestamp	Time that the share was created.
email	string	User's primary email address for user shares; null for group shares.
message	string	The message included in the body of the email that is optionally sent to the recipient. You can specify this attribute in a request, but it is never present in a response.
modifiedAt	timestamp	Time that the share was modified.
name	string	If a user share and user is also a contact, the user's full name. If a group share, the group's name.
scope	string	The scope of this share. One of the following values: ITEM: an item-level share (that is, the specific object to which the share applies is shared with the user or group) WORKSPACE: a workspace-level share (that is, the workspace that contains the object to which the share applies is shared with the user or group)
subject	string	The subject of the email that is optionally sent to notify the recipient. You can specify this attribute in a request, but it is never present in a response.

Report Sharing

Delete Report Share

Example request: delete report share

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

// Set options
var options = {
  reportId: 665829219035012,
  shareId: "AAAQSF82F1eE"
};

// Delete report share
smartsheet.reports.deleteShare(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.ReportResources.ShareResources.DeleteShare(
  665829219035012,            // long reportId
  "AAAQSF82F1eE"              // string shareId
);

smartsheet.reportResources().shareResources().deleteShare(
  665829219035012L,        // long reportId
  "AAAQSF82F1eE"           // string shareId
);

smartsheet_client.Reports.delete_share(
  665829219035012,        # report_id
  'AAAQSF82F1eE')         # share_id

smartsheet.reports.share.delete(
  report_id: 665829219035012,
  share_id: 'AAAQSF82F1eE'
)

Example response

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

DELETE /reports/{reportId}/shares/{shareId}

Deletes the share specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	SHARE_SHEETS

Get Report Share

Example request: get report share

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

// Set options
var options = {
  reportId: 6932724448552836,
  shareId: "AQAISF82FOeE"
};

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

Share share = smartsheet.ReportResources.ShareResources.GetShare(
  6932724448552836,               // long reportId
  "AQAISF82FOeE"                  // string shareId
);

Share share = smartsheet.reportResources().shareResources().getShare(
  665829219035012L,        // long reportId
  "AAAQSF82F1eE"           // string shareId
);

share = smartsheet_client.Reports.get_share(
  6932724448552836,       # report_id
  'AAAQSF82F1eE')         # share_id

share = smartsheet.reports.share.get(
  report_id: 6932724448552836,
  share_id: 'AAABbMomFOeE'
)

Example response

{
  "id": "AQAISF82FOeE",
  "type": "GROUP",
  "groupId": 2331373580117892,
  "name": "Group 1",
  "accessLevel": "ADMIN",
  "scope": "ITEM",
  "createdAt": "2016-02-17T22:24:09Z",
  "modifiedAt": "2016-02-17T22:24:09Z"
}

GET /reports/{reportId}/shares/{shareId}

Gets the share specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Share object
Access Scope	READ_SHEETS

List Report Shares

Example request: list report shares

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

// Set options
var options = {
  reportId: 665829219035012
};

// List report shares
smartsheet.reports.listShares(options)
  .then(function(shareList) {
    console.log(shareList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Share> shares = smartsheet.ReportResources.ShareResources.ListShares(
  665829219035012,        // long reportId
  null,                   // PaginationParameters
  null                    // ShareScope shareScope
);

// Omit pagination parameters
PagedResult<Share> shares = smartsheet.reportResources().shareResources().listShares(
  665829219035012L,        // long reportId
  null,                    // PaginationParameters
  true                     // Boolean includeWorkspaceShares
);

# Sample 1: List all
response = smartsheet_client.Reports.list_shares(include_all=True)
shares = response.result

# Sample 2: Paginate the list
response = smartsheet_client.Reports.list_shares(
  page_size=10,
  page=1)
pages = response.total_pages
shares = response.result

response = smartsheet.reports.share.list(
  report_id: 665829219035012
)
shares = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": "AAAQSF82FOeE",
            "type": "USER",
            "userId": 4583173393803140,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "accessLevel": "OWNER",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:24:09Z"
        },
        {
            "id": "AQAISF82FOeE",
            "type": "GROUP",
            "groupId": 2331373580117892,
            "name": "Group 1",
            "accessLevel": "ADMIN",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:25:08Z"
        }
    ]
}

GET /reports/{reportId}/shares

Gets a list of all users and groups to whom the specified report is shared, and their access level.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional): when specified with a value of workspaceShares, response contains both item-level shares (scope=ITEM) and workspace-level shares (scope=WORKSPACE). This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Share objects NOTE: If the response contains an item-level share (scope=ITEM) and a workspace-level share (scope=WORKSPACE) for the same user or group, the id of those two Share objects is identical, but the scope attribute value can be used to disambiguate the two.
Access Scope	READ_SHEETS

Share Report

Example request: share report

curl 'https://api.smartsheet.com/2.0/reports/{reportId}/shares?sendEmail=true' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"email": "jane.doe@smartsheet.com", "accessLevel": "EDITOR"}]'

// Specify share (to one user as Editor)
var share = [
    {
        "email": "jane.doe@smartsheet.com", 
        "accessLevel": "EDITOR"
    }
];

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

// Share report
smartsheet.reports.share(options)
  .then(function(addressList) {
    console.log(addressList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify share (to one user as Editor)
Share[] shareSpecification = new Share[] { new Share
  {
    Email = "jane.doe@smartsheet.com",
    AccessLevel = AccessLevel.EDITOR
  }
};

// Share report
IList<Share> addressList = smartsheet.ReportResources.ShareResources.ShareTo(
  665829219035012,            // long reportId
  shareSpecification,
  true                        // Nullable<bool> sendEmail
);

// Specify share (to one user as Editor)
Share shareSpecification = new Share()
  .setEmail("jane.doe@smartsheet.com")
  .setAccessLevel(AccessLevel.EDITOR);

// Share report
List<Share> addressList = smartsheet.reportResources().shareResources().shareTo(
  665829219035012L,        // long reportId
  Arrays.asList(shareSpecification),
  true                     // Boolean sendEmail
);

response = smartsheet_client.Reports.share_report(
  665829219035012,        # report_id
  smartsheet.models.Share({
    'access_level': 'EDITOR',
    'email': 'jane.doe@smartsheet.com'
  })
)

body = {
  email: 'jane.doe@smartsheet.com',
  access_level: 'EDITOR',
  subject: 'This report has been shared with you!',
  message: 'This Smartsheet report is ready for your inspection.'
}

response = smartsheet.reports.share.create(
  report_id: 665829219035012,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
        "id": "AAAFeF82FOeE",
        "type": "USER",
        "userId": 1539725208119172,
        "email": "jane.doe@smartsheet.com",
        "name": "Jane Doe",
        "accessLevel": "EDITOR",
        "scope": "ITEM"
    }]
}

POST /reports/{reportId}/shares

Shares a report with the specified users and groups.

If called with a single Share object, and that user or group share already exists, error code 1025 is returned. If called with an array of Share objects, and one or more user or group shares in the array already exist, they are ignored and omitted from the response.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	sendEmail (optional): Either true or false to indicate whether to notify the user by email. Default is false.
Request Body	Share object or an array of Share objects, with the following attributes: accessLevel (required) ccMe (optional): Boolean flag to indicate whether or not to CC the user sharing the sheet. email (optional): the individual share recipient's email address groupId (optional): the group share recipient's group Id message (optional): The message in the body of the email that is optionally sent to the recipient. subject (optional): The subject of the email that is optionally sent to notify the recipient. NOTE: One of email or groupId must be specified, but not both.
Returns	Result object containing either a single Share object or an array of Share objects, corresponding to what was specified in the request. All shares have scope="ITEM".
Errors	If an error occurs because the request specified one or more alternate email addresses, please retry using the primary email address.
Access Scope	SHARE_SHEETS

Update Report Share

Example request: update report share

curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'

// Set the access level to Viewer
var share = {"accessLevel": "VIEWER"};

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

// Update report share
smartsheet.reports.updateShare(options)
  .then(function(updatedShare) {
    console.log(updatedShare);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set the access level to Viewer
Share shareSpecification = new Share
{
  Id = "AAAFeF82FOeE",
  AccessLevel = AccessLevel.VIEWER
};

// Update report share
Share updatedShare = smartsheet.ReportResources.ShareResources.UpdateShare(
  665829219035012,            // long reportId
  shareSpecification
);

// Set the access level to Viewer
Share shareSpecification = new Share();
shareSpecification.setAccessLevel(AccessLevel.VIEWER)
  .setId("AAAFeF82FOeE");   // string shareId

// Update report share
Share updatedShare = smartsheet.reportResources().shareResources().updateShare(
  665829219035012L,                   // long reportId
  shareSpecification
);

updated_share = smartsheet_client.Reports.update_share(
  665829219035012,        # report_id
  'AAAFeF82FOeE',         # share_id
  smartsheet.models.Share({
    'access_level': 'VIEWER'
  })
)

body = {
  access_level: 'VIEWER'
}

response = smartsheet.reports.share.update(
  report_id: 665829219035012,
  share_id: 'AAABbMomFOeE',
  body: body
)

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": "AAAFeF82FOeE",
    "type": "USER",
    "userId": 1539725208119172,
    "email": "jane.doe@smartsheet.com",
    "name": "Jane Doe",
    "accessLevel": "VIEWER",
  "scope": "ITEM"
  }
}

PUT /reports/{reportId}/shares/{shareId}

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Share object limited to the following attribute: accessLevel (string)
Returns	Result object containing the modified Share object
Access Scope	SHARE_SHEETS

Sheet Sharing

Delete Sheet Share

Example request: delete sheet share

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

// Set options
var options = {
  sheetId: 4583614634583940,
  shareId: "AAAASuWWFOeE"
};

// Delete sheet share
smartsheet.sheets.deleteShare(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.SheetResources.ShareResources.DeleteShare(
  4583614634583940,               // long sheetId
  "AAAASuWWFOeE"                  // string shareId
);

smartsheet.sheetResources().shareResources().deleteShare(
  4583614634583940L,       // long sheetId
  "AAAASuWWFOeE"           // string shareId
);

smartsheet_client.Sheets.delete_share(
  4583614634583940,       # sheet_id
  'AAAFeF82FOeE')         # share_id

smartsheet.sheets.share.delete(
  sheet_id: 4583173393803140,
  share_id: 'AAABbMomFOeE'
)

Example response

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

DELETE /sheets/{sheetId}/shares/{shareId}

Deletes the share specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	SHARE_SHEETS

Get Sheet Share

Example request: get sheet share

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

// Set options
var options = {
  sheetId: 4583614634583940,
  shareId: "AQAISF82FOeE"
};

// Get sheet share
smartsheet.sheets.getShare(options)
  .then(function(share) {
    console.log(share);
  })
  .catch(function(error) {
    console.log(error);
  });

Share share = smartsheet.SheetResources.ShareResources.GetShare(
  4583614634583940,           // long sheetId
  "AQAISF82FOeE"              // string shareId
);

Share share = smartsheet.sheetResources().shareResources().getShare(
  4583614634583940L,       // long sheetId
  "AAAASuWWFOeE"           // string shareId
);

share = smartsheet_client.Sheets.get_share(
  4583614634583940,       # sheet_id
  'AAAASuWWFOeE')         # share_id

share = smartsheet.sheets.share.get(
  sheet_id: 4583173393803140,
  share_id: 'AAABbMomFOeE'
)

Example response

{
  "id": "AQAISF82FOeE",
  "type": "GROUP",
  "groupId": 2331373580117892,
  "name": "Group 1",
  "accessLevel": "ADMIN",
  "scope": "ITEM",
  "createdAt": "2016-02-17T22:24:09Z",
  "modifiedAt": "2016-02-17T22:24:09Z"
}

GET /sheets/{sheetId}/shares/{shareId}

Gets the share specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Share object
Access Scope	READ_SHEETS

List Sheet Shares

Example request: list sheet shares

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

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

// List sheet shares
smartsheet.sheets.listShares(options)
  .then(function(shareList) {
    console.log(shareList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Share> shares = smartsheet.SheetResources.ShareResources.ListShares(
  4583614634583940,               // long sheetId
  null                            // PaginationParameters
);

// Omit pagination parameters
PagedResult<Share> shares = smartsheet.sheetResources().shareResources().listShares(
  4583614634583940L,       // long sheetId
  null,                    // PaginationParameters
  true                     // Boolean includeWorkspaceShares
);

# Sample 1: List all
response = smartsheet_client.Sheets.list_shares(
  4583614634583940,       # sheet_id
  include_all=True)
shares = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Sheets.list_shares(
  4583614634583940,       # sheet_id
  page_size=10,
  page=1)
pages = response.total_pages
shares = response.data

response = smartsheet.sheets.share.list(
  sheet_id: 4583173393803140
)
shares = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": "AAAQSF82FOeE",
            "type": "USER",
            "userId": 4583173393803140,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "accessLevel": "OWNER",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:24:09Z"
        },
        {
            "id": "AQAISF82FOeE",
            "type": "GROUP",
            "groupId": 2331373580117892,
            "name": "Group 1",
            "accessLevel": "ADMIN",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:25:08Z"
        }
    ]
}

GET /sheets/{sheetId}/shares

Gets a list of all users and groups to whom the specified sheet is shared, and their access level.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional): when specified with a value of workspaceShares, response contains both item-level shares (scope=ITEM) and workspace-level shares (scope=WORKSPACE). This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Share objects NOTE: If the response contains an item-level share (scope=ITEM) and a workspace-level share (scope=WORKSPACE) for the same user or group, the id of those two Share objects is identical, but the scope attribute value can be used to disambiguate the two.
Access Scope	READ_SHEETS

Share Sheet

Example request: share sheet

curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/shares?sendEmail=true' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"email": "jane.doe@smartsheet.com", "accessLevel": "EDITOR"}]'

// Specify share (to one user as Editor)
var share = [
    {
        "email": "jane.doe@smartsheet.com", 
        "accessLevel": "EDITOR"
    }
];

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

// Share sheet
smartsheet.sheets.share(options)
  .then(function(addressList) {
    console.log(addressList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify share (to one user as Editor)
Share[] shareSpecification = new Share[] { new Share
  {
    Email = "jane.doe@smartsheet.com",
    AccessLevel = AccessLevel.EDITOR
  }
};

// Share sheet
IList<Share> addressList = smartsheet.SheetResources.ShareResources.ShareTo(
  4583614634583940,               // long sheetId
  shareSpecification,
  true                            // Nullable<bool> sendEmail
);

// Specify share (to one user as Editor)
Share shareSpecification = new Share()
  .setEmail("jane.doe@smartsheet.com")
  .setAccessLevel(AccessLevel.EDITOR);

// Share sheet
List<Share> addressList = smartsheet.sheetResources().shareResources().shareTo(
  4583614634583940L,                    // long sheetId
  (Arrays.asList(shareSpecification)),
  true                                  // Boolean sendEmail
);

response = smartsheet_client.Sheets.share_sheet(
  4583614634583940,       # sheet_id
  smartsheet.models.Share({
    'access_level': 'EDITOR',
    'email': 'jane.doe@smartsheet.com'
  }),
  True                    # sendEmail
)

body = {
  email: 'jane.doe@smartsheet.com',
  access_level: 'EDITOR',
  subject: 'This sheet has been shared with you!',
  message: 'This Smartsheet is ready for your inspection.'
}

response = smartsheet.sheets.share.create(
  sheet_id: 4583173393803140,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
        "id": "AAAFeF82FOeE",
        "type": "USER",
        "userId": 1539725208119172,
        "email": "jane.doe@smartsheet.com",
        "name": "Jane Doe",
        "accessLevel": "EDITOR",
        "scope": "ITEM"
    }]
}

POST /sheets/{sheetId}/shares

Shares a sheet with the specified users and groups.

If called with a single Share object, and that user or group share already exists, error code 1025 is returned. If called with an array of Share objects, and one or more user or group shares in the array already exist, they are ignored and omitted from the response.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	sendEmail (optional): Either true or false to indicate whether to notify the user by email. Default is false.
Request Body	Share object or an array of Share objects, with the following attributes: accessLevel (required) ccMe (optional): Boolean flag to indicate whether or not to CC the user sharing the sheet. email (optional): the individual share recipient's email address groupId (optional): the group share recipient's group Id message (optional): The message in the body of the email that is optionally sent to the recipient. subject (optional): The subject of the email that is optionally sent to notify the recipient. NOTE: One of email or groupId must be specified, but not both.
Returns	Result object containing either a single Share object or an array of Share objects, corresponding to what was specified in the request. All shares have scope="ITEM".
Errors	If an error occurs because the request specified one or more alternate email addresses, please retry using the primary email address.
Access Scope	SHARE_SHEETS

Update Sheet Share

Example request: update sheet share

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares/{shareId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'

// Set access level to Viewer
var shareSpecification = {"accessLevel": "VIEWER"};

// Set options
var options = {
  sheetId: 1696801624483716,
  shareId: "AAAHAYImFOeE",
  body: shareSpecification
};

// Update sheet share
smartsheet.sheets.updateShare(options)
  .then(function(updatedShare) {
    console.log(updatedShare);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set the access level to Viewer
Share shareSpecification = new Share
{
  Id = "AAAFeF82FOeE",
  AccessLevel = AccessLevel.VIEWER
};

// Update sheet share
Share updatedShare = smartsheet.SheetResources.ShareResources.UpdateShare(
  4583614634583940,               // long sheetId
  shareSpecification
);

// Set the access level to Viewer
Share shareSpecification = new Share()
  .setEmail("jane.doe@smartsheet.com")
  .setAccessLevel(AccessLevel.EDITOR);

// Update sheet share
Share updatedShare = smartsheet.sheetResources().shareResources().updateShare(
  4583614634583940L,       // long sheetId
  shareSpecification
);

updated_share = smartsheet_client.Sheets.update_share(
  4583614634583940,       # sheet_id
  'AAAFeF82FOeE',         # share_id
  smartsheet.models.Share({
    'access_level': 'VIEWER'
  })
)

body = {
  access_level: 'VIEWER'
}

response = smartsheet.sheets.share.update(
  sheet_id: 4583173393803140,
  share_id: 'AAABbMomFOeE',
  body: body
)

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": "AAAFeF82FOeE",
    "type": "USER",
    "userId": 1539725208119172,
    "email": "jane.doe@smartsheet.com",
    "name": "Jane Doe",
    "accessLevel": "VIEWER",
  "scope": "ITEM"
  }
}

PUT /sheets/{sheetId}/shares/{shareId}

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Share object limited to the following attribute: accessLevel (string)
Returns	Result object containing the modified Share object
Access Scope	SHARE_SHEETS

Sight Sharing

Delete Sight Share

Example request: delete Sight share

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

// Set options
var options = {
  sightId: 6327127650920324,
  shareId: "AAABbMomFOeE"
}

// Delete Sight share
smartsheet.sights.deleteShare(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

smartsheet.sightResources().shareResources().deleteShare(
  6327127650920324L,           // long sightId
  "AAABbMomFOeE"               // string shareId
);

smartsheet_client.Sights.delete_share(
  6327127650920324,       # sight_id
  'AAACOqOmFOeE')         # share_id

smartsheet.sights.share.delete(
  sight_id: 6327127650920324,
  share_id: 'AAABbMomFOeE'
)

Example response

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

DELETE /sights/{sightId}/shares/{shareId}

Deletes the share specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	SHARE_SIGHTS

Get Sight Share

Example request: get Sight share

curl https://api.smartsheet.com/2.0/sights/{sightId}/shares/{shareId}
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" 

// Set options
var options = {
  sightId: 6327127650920324,
  shareId: "AAABbMomFOeE"
}

// Get Sight share
smartsheet.sights.getShare(options)
  .then(function(share) {
    console.log(share);
  })
  .catch(function(error) {
    console.log(error);
  });

Share share = smartsheet.SightResources.ShareResources.GetShare(
  6327127650920324,           // long sightId
  "AAABbMomFOeE"              // string shareId
);

Share share = smartsheet.sightResources().shareResources().getShare(
  6327127650920324L,           // long sightId
  "AAABbMomFOeE"              // string shareId
);

share = smartsheet_client.Sights.get_share(
  6327127650920324,       # sight_id
  'AAACOqOmFOeE')         # share_id

share = smartsheet.sights.share.get(
  sight_id: 6327127650920324,
  share_id: 'AAABbMomFOeE'
)

Example response

{
  "id": "AQAISF82FOeE",
  "type": "GROUP",
  "groupId": 2331373580117892,
  "name": "Group 1",
  "accessLevel": "ADMIN",
  "scope": "ITEM",
  "createdAt": "2016-02-17T22:24:09Z",
  "modifiedAt": "2016-02-17T22:24:09Z"
}

GET /sights/{sightId}/shares/{shareId}

Gets the share specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Share object
Access Scope	READ_SIGHTS

List Sight Shares

Example request: list Sight shares

curl https://api.smartsheet.com/2.0/sights/{sightId}/shares
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" 

// Set options
var options = {
  sightId: 6327127650920324
}

// List Sight shares
smartsheet.sights.listShares(options)
  .then(function(shareList) {
    console.log(shareList);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// [todo]

# Sample 1: List all
response = smartsheet_client.Sights.list_shares(
  6327127650920324,       # sight_id
  include_all=True)
shares = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Sights.list_shares(
  6327127650920324,       # sight_id
  page_size=10,
  page=1)
pages = response.total_pages
shares = response.data

response = smartsheet.sights.share.list(
  sight_id: 6327127650920324
)
shares = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": "AAAQSF82FOeE",
            "type": "USER",
            "userId": 4583173393803140,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "accessLevel": "OWNER",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:24:09Z"
        },
        {
            "id": "AQAISF82FOeE",
            "type": "GROUP",
            "groupId": 2331373580117892,
            "name": "Group 1",
            "accessLevel": "ADMIN",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:25:08Z"
        }
    ]
}

GET /sights/{sightId}/shares

Gets a list of all users and groups to whom the specified Sight is shared, and their access level.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional): when specified with a value of workspaceShares, response contains both item-level shares (scope=ITEM) and workspace-level shares (scope=WORKSPACE). This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Share objects NOTE: If the response contains an item-level share (scope=ITEM) and a workspace-level share (scope=WORKSPACE) for the same user or group, the id of those two Share objects is identical, but the scope attribute value can be used to disambiguate the two.
Access Scope	READ_SIGHTS

Share Sight

Example request: share Sight

curl 'https://api.smartsheet.com/2.0/sights/{sightId}/shares?sendEmail=true'
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
-H "Content-Type: application/json"
-X POST
-d '[{"email": "jane.doe@smartsheet.com", "accessLevel": "VIEWER"}]'

// Specify share (to one user as Viewer)
var share = [
  {
    "email": "jane.doe@smartsheet.com",
    "accessLevel": "VIEWER"
  }
];

// Set options
var options = {
  sightId: 6327127650920324,
  body: share
};

// Share Sight
smartsheet.sights.share(options)
  .then(function(addressList) {
    console.log(addressList);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// Specify share (to one user as Viewer)
Share shareSpecification = new Share()
  .setEmail("jane.doe@smartsheet.com")
  .setAccessLevel(AccessLevel.VIEWER);

// Share Sight
List<Share> addressList = smartsheet.sightResources().shareResources().shareTo(
  4583614634583940L,                    // long sightId
  (Arrays.asList(shareSpecification)),
  true                                  // Boolean sendEmail
);

response = smartsheet_client.Sights.share_sight(
  6327127650920324,       # sight_id
  smartsheet.models.Share({
    'access_level': 'VIEWER',
    'email': 'jane.doe@smartsheet.com'
  }),
  True                    # sendEmail
)

body = {
  email: 'jane.doe@smartsheet.com',
  access_level: 'VIEWER',
  subject: 'This Sight has been shared with you!',
  message: 'This Smartsheet Sight is ready for your inspection.'
}

response = smartsheet.sights.share.create(
  sight_id: 6327127650920324,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
        "id": "AAAFeF82FOeE",
        "type": "USER",
        "userId": 1539725208119172,
        "email": "jane.doe@smartsheet.com",
        "name": "Jane Doe",
        "accessLevel": "EDITOR",
        "scope": "ITEM"
    }]
}

POST /sights/{sightId}/shares

Shares a Sight with the specified users and groups.

If called with a single Share object, and that user or group share already exists, error code 1025 is returned. If called with an array of Share objects, and one or more user or group shares in the array already exist, they are ignored and omitted from the response.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	sendEmail (optional): Either true or false to indicate whether to notify the user by email. Default is false.
Request Body	Share object or an array of Share objects, with the following attributes: accessLevel (required) ccMe (optional): Boolean flag to indicate whether to CC the user sharing the sheet. email (optional): the individual share recipient's email address groupId (optional): the group share recipient's group Id message (optional): The message in the body of the email that is optionally sent to the recipient. subject (optional): The subject of the email that is optionally sent to notify the recipient. NOTE: One of email or groupId must be specified, but not both.
Returns	Result object containing either a single Share object or an array of Share objects, corresponding to what was specified in the request. All shares have scope=ITEM.
Errors	If an error occurs because the request specified one or more alternate email addresses, please retry using the primary email address.
Access Scope	SHARE_SIGHTS

Update Sight Share

Example request: update Sight share

curl https://api.smartsheet.com/2.0/sights/{sightId}/shares/{shareId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'

// Set access level to Viewer
var shareSpecification = {"accessLevel": "VIEWER"};

// Set options
var options = {
  sightId: 6327127650920324,
  shareId: "AAALRqomFOeE",
  body: shareSpecification
};

// Update Sight share
smartsheet.sights.updateShare(options)
  .then(function(updatedShare) {
    console.log(updatedShare);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// Set the access level to Viewer
Share shareSpecification = new Share();
shareSpecification.setAccessLevel(AccessLevel.VIEWER)
  .setId("AAAFeF82FOeE");   // string shareId

// Update Sight share
Share updatedShare = smartsheet.sightResources().shareResources().updateShare(
  6327127650920324L,       // long sightId
  shareSpecification
);

updated_share = smartsheet_client.Sights.update_share(
  6327127650920324,       # sight_id
  'AAALRqomFOeE',         # share_id
  smartsheet.models.Share({
    'access_level': 'VIEWER'
  })
)

body = {
  access_level: 'VIEWER'
}

response = smartsheet.sights.share.update(
  sight_id: 6327127650920324,
  share_id: 'AAABbMomFOeE',
  body: body
)

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": "AAAFeF82FOeE",
    "type": "USER",
    "userId": 1539725208119172,
    "email": "jane.doe@smartsheet.com",
    "name": "Jane Doe",
    "accessLevel": "VIEWER",
  "scope": "ITEM"
  }
}

PUT /sights/{sightId}/shares/{shareId}

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Share object limited to the following attribute: accessLevel (string)
Returns	Result object containing the modified Share object
Access Scope	SHARE_SIGHTS

Workspace Sharing

Delete Workspace Share

Example request: delete workspace share

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  workspaceId: 1656220827314052,
  shareId: "AAAEQesWFOeE"
};

// Delete workspace share
smartsheet.workspaces.deleteShare(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.WorkspaceResources.ShareResources.DeleteShare(
  1656220827314052,               // long workspaceId
  "AAAEQesWFOeE"                  // string shareId
);

smartsheet.workspaceResources().shareResources().deleteShare(
  1656220827314052L,       // long workspaceId
  "AAAEQesWFOeE"           // string shareId
);

smartsheet_client.Workspaces.delete_share(
  1656220827314052,           # workspace_id
  'AAAEQesWFOeE')             # share_id

smartsheet.workspaces.share.delete(
  workspace_id: 1656220827314052,
  share_id: 'AAABbMomFOeE'
)

Example response

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

DELETE /workspaces/{workspaceId}/shares/{shareId}

Deletes the share specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Get Workspace Share

Example request: get workspace share

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" 

// Set options
var options = {
  workspaceId: 1656220827314052,
  shareId: "AQAISF82FOeE"
};

// Get workspace share
smartsheet.workspaces.getShare(options)
  .then(function(share) {
    console.log(share);
  })
  .catch(function(error) {
    console.log(error);
  });

Share share = smartsheet.WorkspaceResources.ShareResources.GetShare(
  1656220827314052,           // long workspaceId
  "AQAISF82FOeE"              // string shareId
);

Share share = smartsheet.workspaceResources().shareResources().getShare(
  1656220827314052L,       // long workspaceId
  "AQAISF82FOeE"           // string shareId
);

share = smartsheet_client.Sheets.get_share(
  1656220827314052,           # workspace_id
  'AAAEQesWFOeE')             # share_id

share = smartsheet.workspaces.share.get(
  workspace_id: 1656220827314052,
  share_id: 'AAABbMomFOeE'
)

Example response

{
  "id": "AQAISF82FOeE",
  "type": "GROUP",
  "groupId": 2331373580117892,
  "name": "Group 1",
  "accessLevel": "ADMIN",
  "scope": "ITEM",
  "createdAt": "2016-02-17T22:24:09Z",
  "modifiedAt": "2016-02-17T22:24:09Z"
}

GET /workspaces/{workspaceId}/shares/{shareId}

Gets the share specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Share object
Access Scope	READ_SHEETS

List Workspace Shares

Example request: list workspace shares

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" 

// Set options
var options = {
  workspaceId: 1656220827314052
};

// List workspace shares
smartsheet.workspaces.listShares(options)
  .then(function(shareList) {
    console.log(shareList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Share> shares = smartsheet.WorkspaceResources.ShareResources.ListShares(
  1656220827314052,               // long workspaceId
  null                            // PaginationParameters
);

// Omit pagination parameters
PagedResult<Share> shares = smartsheet.workspaceResources().shareResources().listShares(
  1656220827314052L,       // long workspaceId
  null,                    // PaginationParameters
  true                     // Boolean includeWorkspaceShares
);

# Sample 1: List all
response = smartsheet_client.Workspaces.list_shares(
  1656220827314052,       # workspace_id
  include_all=True)
shares = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Workspaces.list_shares(
  1656220827314052,       # workspace_id
  page_size=10,
  page=1)
pages = response.total_pages
shares = response.data

response = smartsheet.workspaces.share.list(
  workspace_id: 1656220827314052
)
shares = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": "AAAQSF82FOeE",
            "type": "USER",
            "userId": 4583173393803140,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "accessLevel": "OWNER",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:24:09Z"
        },
        {
            "id": "AQAISF82FOeE",
            "type": "GROUP",
            "groupId": 2331373580117892,
            "name": "Group 1",
            "accessLevel": "ADMIN",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:25:08Z"
        }
    ]
}

GET /workspaces/{workspaceId}/shares

Gets a list of all users and groups to whom the specified workspace is shared, and their access level.

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 Share objects
Access Scope	READ_SHEETS

Share Workspace

Example request: share workspace

curl 'https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares?sendEmail=true' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"email": "jane.doe@smartsheet.com", "accessLevel": "EDITOR"}]'

// Specify share (to one user as Editor)
var shares = [
    {
        "email": "john.doe@smartsheet.com",
        "accessLevel": "EDITOR"
    }
];

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

// Share workspace
smartsheet.workspaces.share(options)
    .then(function(addressList) {
        console.log(addressList);
    })
    .catch(function(error) {
        console.log(error);
    });

// Specify share (to one user as Editor)
Share[] shareSpecification = new Share[] { new Share
  {
    Email = "jane.doe@smartsheet.com",
    AccessLevel = AccessLevel.EDITOR
  }
};

// Share workspace
IList<Share> addressList = smartsheet.WorkspaceResources.ShareResources.ShareTo(
  7960873114331012,               // long workspaceId
  shareSpecification,
  true                            // Nullable<bool> sendEmail
);

// Specify share (to one user as Editor)
Share shareSpecification = new Share()
  .setEmail("jane.doe@smartsheet.com")
  .setAccessLevel(AccessLevel.EDITOR);

// Share workspace
List<Share> addressList = smartsheet.workspaceResources().shareResources().shareTo(
  7960873114331012L,                    // long workspaceId
  (Arrays.asList(shareSpecification)),
  true                                  // Boolean sendEmail
);

response = smartsheet_client.Workspaces.share_workspace(
  1656220827314052,       # workspace_id
  smartsheet.models.Share({
    'access_level': 'EDITOR',
    'email': 'jane.doe@smartsheet.com'
  })
)

body = {
  email: 'jane.doe@smartsheet.com',
  access_level: 'EDITOR',
  subject: 'This workspace has been shared with you!',
  message: 'This Smartsheet workspace is ready for your inspection.'
}

response = smartsheet.workspaces.share.create(
  workspace_id: 1656220827314052,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
        "id": "AAAFeF82FOeE",
        "type": "USER",
        "userId": 1539725208119172,
        "email": "jane.doe@smartsheet.com",
        "name": "Jane Doe",
        "accessLevel": "EDITOR",
        "scope": "ITEM"
    }]
}

POST /workspaces/{workspaceId}/shares

Shares a workspace with the specified users and groups.

If called with a single Share object, and that user or group share already exists, error code 1025 is returned. If called with an array of Share objects, and one or more user or group shares in the array already exist, they are ignored and omitted from the response.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	sendEmail (optional): Either true or false to indicate whether to notify the user by email. Default is false.
Request Body	Share object or an array of Share objects, with the following attributes: accessLevel (required) ccMe (optional): Boolean that indicates whether to CC the user sharing the sheet. email (optional): the individual share recipient's email address groupId (optional): the group share recipient's group Id message (optional): The message in the body of the email that is optionally sent to the recipient. subject (optional): The subject of the email that is optionally sent to notify the recipient. NOTE: One of email or groupId must be specified, but not both.
Returns	Result object containing either a single Share object or an array of Share objects, corresponding to what was specified in the request.
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_WORKSPACES

Update Workspace Share

Example request: update workspace share

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'

// Set access level to Viewer
var share = {"accessLevel": "VIEWER"};

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

// Update workspace share
smartsheet.workspaces.updateShare(options)
  .then(function(updatedShare) {
    console.log(updatedShare);
  })
  .catch(function(error) {
    console.log(error);
  });

// Set the access level to Viewer
Share shareSpecification = new Share
{
  Id = "AAAFeF82FOeE",
  AccessLevel = AccessLevel.VIEWER
};

// Update workspace share
Share updatedShare = smartsheet.WorkspaceResources.ShareResources.UpdateShare(
  1656220827314052,             // long workspaceId
  shareSpecification
);

// Set the access level to Viewer
Share shareSpecification = new Share();
shareSpecification.setAccessLevel(AccessLevel.VIEWER)
  .setId("AAAFeF82FOeE");   // string shareId

// Update workspace share
Share updatedShare = smartsheet.workspaceResources().shareResources().updateShare(
  1656220827314052L,   // long workspaceId
  shareSpecification
);

updated_share = smartsheet_client.Workspaces.update_share(
  1656220827314052,       # workspace_id
  'AAAFeF82FOeE',         # share_id
  smartsheet.models.Share({
    'access_level': 'VIEWER'
  })
)

body = {
  access_level: 'VIEWER'
}

response = smartsheet.workspaces.share.update(
  workspace_id: 1656220827314052,
  share_id: 'AAABbMomFOeE',
  body: body
)

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": "AAAFeF82FOeE",
    "type": "USER",
    "userId": 1539725208119172,
    "email": "jane.doe@smartsheet.com",
    "name": "Jane Doe",
    "accessLevel": "VIEWER",
  "scope": "ITEM"
  }
}

PUT /workspaces/{workspaceId}/shares/{shareId}

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Share object limited to the following attribute: accessLevel (string)
Returns	Result object containing the modified Share object
Access Scope	ADMIN_WORKSPACES

Sheets

A sheet can exist in a user's Sheets folder (Home), in a folder, or in a workspace. It is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

Objects

Sheet Object

Example: Sheet object

{
  "accessLevel": "OWNER",
  "projectSettings": {
    "workingDays": [],
    "nonWorkingDays": [],
    "lengthOfDay": 6
  },
  "columns": [],
  "createdAt": "2012-07-24T18:22:29-07:00",
  "id": 4583173393803140,
  "modifiedAt": "2012-07-24T18:30:52-07:00",
  "name": "sheet 1",
  "permalink": "https://app.smartsheet.com/b/home?lx=pWNSDH9itjBXxBzFmyf-5w",
  "rows": []
}

id	number	Sheet Id
fromId	number	The Id of the template from which to create the sheet. This attribute can be specified in a request, but is never present in a response.
ownerId	number	User Id of the sheet owner
accessLevel	string	User's permissions on the sheet
attachments	Attachment[]	Array of Attachment objects Only returned if the include query string parameter contains attachments.
columns	Column[]	Array of Column objects
createdAt	timestamp	Time that the sheet was created
crossSheetReferences	CrossSheetReference[]	Array of CrossSheetReference objects Only returned if the include query string parameter contains crossSheetReferences.
dependenciesEnabled	Boolean	Indicates whether dependencies are enabled
discussions	Discussion[]	Array of Discussion objects Only returned if the include query string parameter contains discussions.
effectiveAttachmentOptions	array	Array of enum strings (see Attachment.attachmentType) indicating the allowable attachment options for the current user and sheet
favorite	Boolean	Returned only if the user has marked this sheet as a favorite in their Home tab (value = true)
ganttEnabled	Boolean	Indicates whether "Gantt View" is enabled
hasSummaryFields	Boolean	Indicates whether a sheet summary is present
modifiedAt	timestamp	Time that the sheet was modified
name	string	Sheet name
owner	string	Email address of the sheet owner
permalink	string	URL that represents a direct link to the sheet in Smartsheet
projectSettings	ProjectSettings	Sheet's project settings containing the working days, non-working days, and length of day for a project sheet
readOnly	Boolean	Returned only if the sheet belongs to an expired trial (value = true)
resourceManagementEnabled	Boolean	Indicates that resource management is enabled
rows	Row[]	Array of Row objects
showParentRowsForFilters	Boolean	Returned only if there are column filters on the sheet. Value = true if "show parent rows" is enabled for the filters.
source	Source	A Source object indicating the report, sheet, Sight (aka dashboard), or template from which this sheet was created, if any
summary	SheetSummary	A SheetSummary object containing a list of defined fields and values for the sheet.
totalRowCount	number	The total number of rows in the sheet
userPermissions	SheetUserPermissions	A SheetUserPermissions object indicating what summary operations are possible for the current user
userSettings	SheetUserSettings	A SheetUserSettings object containing the current user's sheet-specific settings.
version	number	A number that is incremented every time a sheet is modified
workspace	Workspace	A Workspace object containing the workspace Id and name.

Criteria Object

Example: Criteria object

{
  "operator": "IS_ONE_OF",
  "values": [
    "Complete"
  ],
  "columnId": 675838380271492
}

columnId	number	Column Id
operator	string	One of the following values: BETWEEN CONTAINS EQUAL or NOT_EQUAL FUTURE GREATER_THAN or LESS_THAN IS_BLANK or IS_NOT_BLANK IS_CHECKED or IS_NOT_CHECKED IS_DATE or IS_NOT_DATE IS_NUMBER or IS_NOT_NUMBER LAST_N_DAYS or NEXT_N_DAYS PAST TODAY
values	array	Present if a custom filter criteria's operator has one or more arguments.

Filters Object

Example: Filters object

{
  "id": 7182478625531780,
  "filterType": "PERSONAL",
  "query": {
    "operator": "AND",
    "criteria": [],
    "includeParent": false
  }
}

Smartsheet users can define and save personal column filters on sheets they can view. To see whether a row has been included or excluded with a filter, invoke the include=filters query string, which returns a row.filteredOut = true or false response for rows that are excluded by a filter. To see how the filter has been defined, invoke the include=filterDefinitions query string parameter.

id	number	Filters Id
criteria	Criteria[]	An array of Criteria objects specifying custom criteria against which to match cell values.
excludeSelected	Boolean	If true, rows containing cells matching the values or criteria items are excluded instead of included.
filterType	string	One of the following values: PERSONAL or SHARED
includeParent	Boolean	If true, indicates that "show parent rows" is enabled for the filters.
operator	string	One of the following values: BETWEEN CONTAINS EQUAL or NOT_EQUAL FUTURE GREATER_THAN or LESS_THAN IS_BLANK or IS_NOT_BLANK IS_CHECKED or IS_NOT_CHECKED IS_DATE or IS_NOT_DATE IS_NUMBER or IS_NOT_NUMBER LAST_N_DAYS or NEXT_N_DAYS PAST TODAY
query	object	Contains operator and Criteria object.
values	array	Present if a custom filter criteria's operator has one or more arguments.

ProjectSettings Object

Represents the project settings dependencies for a specific sheet. Project settings may be updated on sheets that the user has editor access.

lengthOfDay	number	Length of a workday for a project sheet. Valid value must be above or equal to 1 hour, and less than or equal to 24 hours.
nonWorkingDays	timestamp[]	Non-working days for a project sheet. The format for the timestamp array must be an array of strings that are valid ISO-8601 dates ('YYYY-MM-DD').
workingDays	String[]	Working days of a week for a project sheet. Valid values must be an array of strings of days of the week: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, or SUNDAY

SheetPublish Object

icalEnabled	Boolean	If true, a webcal is available for the calendar in the sheet.
icalUrl	string	URL for iCal view of the published sheet Only returned in a response if icalEnabled = true.
readOnlyFullAccessibleBy	string	Indicates who can access the 'Read-Only Full' view of the published sheet: ALL -- available to anyone who has the link. ORG -- available only to members of the sheet owner's Smartsheet organization account. 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 sheet. Must be one of the following values: CALENDAR, CARD, or GRID.
readOnlyFullEnabled	Boolean	If true, a rich version of the sheet 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 sheet Only returned in a response if readOnlyFullEnabled = true.
readOnlyLiteEnabled	Boolean	If true, a lightweight version of the sheet is published without row attachments and discussions.
readOnlyLiteSslUrl	string	URL for 'Read-Only' view of the published sheet when SSL is enabled.
readOnlyLiteUrl	string	URL for 'Read-Only HTML' view of the published sheet Only returned in a response if readOnlyLiteEnabled = true.
readWriteAccessibleBy	string	Indicates who can access the 'Edit by Anyone' view of the published sheet: ALL -- available to anyone who has the link. ORG -- available only to members of the sheet owner's Smartsheet organization account. Only returned in a response if readWriteEnabled = true.
readWriteDefaultView	string	Indicates which view the user has set for a read-write, default view of the published sheet. Must be one of the following values: CALENDAR, CARD, or GRID.
readWriteEnabled	Boolean	If true, a rich version of the sheet is published with the ability to edit cells and manage attachments and discussions.
readWriteShowToolbar	Boolean	DEPRECATED Indicates whether the left nav toolbar is displayed. The default, or true, is to display the toolbar. If false, hides the toolbar.
readWriteUrl	string	URL for 'Edit by Anyone' view of the published sheet Only returned in a response if readWriteEnabled = true.

SheetSummary Object

Represents the entire summary, or a list of defined fields and values, for a specific sheet.

fields	SummaryField[]	Array of summary (or metadata) fields defined on the sheet.

SheetUserPermissions Object

Describes the current user's editing permissions for a specific sheet.

summaryPermissions	string	One of ADMIN: full control over fields READ_DELETE: sheet is owned by an individual account that doesn't have summary capabilities. If a summary exists, the only possible operations are GET and DELETE fields. READ_ONLY READ_WRITE: can edit values of existing fields, but not create or delete fields, nor modify field type.

SheetUserSettings Object

Represents individual user settings for a specific sheet. User settings may be updated even on sheets where the current user only has read access (for example, viewer permissions or a read-only sheet).

criticalPathEnabled	Boolean	Does this user have "Show Critical Path" turned on for this sheet? NOTE: This setting only has an effect on project sheets with dependencies enabled.
displaySummaryTasks	Boolean	Does this user have "Display Summary Tasks" turned on for this sheet? Applies only to sheets where "Calendar View" has been configured.

SortCriterion Object

columnId	number	Column Id
direction	string	The direction for the sort. Must be one of the following values: ASCENDING (default) or DESCENDING

SortSpecifier Object

sortCriteria	SortCriterion[]	Specifies sort order. Array is in priority order.

Source Object

id	number	Id of the report, sheet, Sight (aka dashboard), or template from which the enclosing report, sheet, Sight, or template was created
type	string	report, sheet, sight, or template

SummaryField Object

id	number	SummaryField Id
contactOptions	ContactOption[]	Array of ContactOption objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST
createdAt	timestamp	Time of creation
createdBy	User	User object containing name and email of the summaryField's author
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 column has a non-default format applied to it.
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 field.value = "#CIRCULAR REFERENCE".
hyperlink	Hyperlink	A hyperlink to a URL, sheet, or report
image	Image	The image that the field contains. Only returned if the field contains an image.
index	number	Field index or position. This number is zero-based.
locked	Boolean	Indicates whether the field is locked. In a response, a value of true indicates that the field has been locked by the sheet owner or the admin.
lockedForUser	Boolean	Indicates whether the field is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.
modifiedAt	timestamp	Time of last modification
modifiedBy	User	User object containing name and email of the summaryField's author
objectValue	ObjectValue	Required for date and contact fields
options	string[]	When applicable for PICKLIST column type. Array of the options available for the field
symbol	string	When applicable for PICKLIST column type. See Symbol Columns.
title	string	Arbitrary name, must be unique within summary
type	string	One of: ABSTRACT_DATETIME CHECKBOX CONTACT_LIST DATE DATETIME DURATION PICKLIST PREDECESSOR TEXT_NUMBER See Column Types.
validation	Boolean	Indicates whether summary field values are restricted to the type

Copy Sheet

Example request: copy sheet

curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/copy?include=data,attachments'
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
-H "Content-Type: application/json"
-d '{
  "destinationType": "folder",
  "destinationId": 7960873114331012,
  "newName": "newSheetName"
}'
-X POST

// Set destination information
var body = {
  destinationType: "home",
  newName: "newSheetName"
};

// Set elements to copy
var params = {
  include: "attachments,data",
  includeAll: true
};

// Set options
var options = {
  sheetId: 7254137655060356,
  body: body,
  queryParameters: params
};

// Copy sheet
smartsheet.sheets.copySheet(options)
  .then(function(copiedSheet) {
    console.log(copiedSheet);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination {
  DestinationId = 3791509922310020,               // long destinationFolderId
  DestinationType = DestinationType.FOLDER,
  NewName = "newSheetName"
};

// Sample 1: Omit 'include' parameter
Sheet sheet = smartsheet.SheetResources.CopySheet(
  9283173393803140,                               // long sheetId
  destination,
  null                                            // IEnumerable<SheetCopyInclusion> include
);

// Sample 2: Specify 'include' parameter with value of "data"
Sheet sheet = smartsheet.SheetResources.CopySheet(
  9283173393803140,                               // long sheetId
  destination,
  new SheetCopyInclusion[] { SheetCopyInclusion.DATA }
);

// Specify destination
ContainerDestination destination = new ContainerDestination()
  .setDestinationType(DestinationType.FOLDER)
  .setDestinationId(9283173393803140L)
  .setNewName("newSheetName");

// Sample 1: Omit 'include' parameter
Sheet sheet = smartsheet.sheetResources().copySheet(
  4583173393803140L,                          // long sheetId
  destination,
  null                                        // EnumSet<SheetCopyInclusion> includes
);

// Sample 2: Specify 'include' parameter with value of "data"
Sheet sheet = smartsheet.sheetResources().copySheet(
  4583173393803140L,                         // long sheetId
  destination,
  EnumSet.of(SheetCopyInclusion.DATA)
);

response = smartsheet_client.Sheets.copy_sheet(
  4583173393803140,                               # sheet_id
  smartsheet.models.ContainerDestination({
    'destination_type': 'folder',               # folder, workspace, or home
    'destination_id': 9283173393803140,         # folder_id
    'new_name': 'newSheetName'
  })
)

body = {
  destination_type: 'folder',
  destination_id: 9283173393803140,
  new_name: 'newSheetName'
}

smartsheet.sheets.copy(
  sheet_id: 4583173393803140,
  body: body
)

Example response

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

POST /sheets/{sheetId}/copy

Creates a copy of the specified sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of elements to copy: attachments cellLinks -- includes cross-sheet references 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.
	exclude (optional) -- when specified with a value of sheetHyperlinks, excludes this category from the response
Request Body	ContainerDestination object
Returns	Result object containing a Sheet object for the newly created sheet, limited to the following attributes: accessLevel id name permalink
Access Scope	CREATE_SHEETS

Create Sheet

Create Sheet in "Sheets" Folder

Example request: create sheet in "Sheets" folder

curl https://api.smartsheet.com/2.0/sheets \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet","columns":[{"title":"Favorite","type":"CHECKBOX","symbol":"STAR"}, {"title":"Primary Column", "primary":true,"type":"TEXT_NUMBER"}]}'

// Specify sheet properties
var sheet = {
  "name": "newsheet",
  "columns": [
    {
      "title": "Favorite",
      "type": "CHECKBOX",
      "symbol": "STAR"
    },
    {
      "title": "Primary Column",
      "primary": true,
      "type": "TEXT_NUMBER"
    }
  ]
};

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

// Create sheet in "Sheets" folder
smartsheet.sheets.createSheet(options)
    .then(function(newSheet) {
        console.log(newSheet);
    })
    .catch(function(error) {
        console.log(error);
    });

// Specify properties of the first column
Column columnA = new Column
{
  Title = "Favorite",
  Primary = false,
  Type = ColumnType.CHECKBOX,
  Symbol = Symbol.STAR
};

// Specify properties of the second column
Column columnB = new Column
{
  Title = "Primary Column",
  Primary = true,
  Type = ColumnType.TEXT_NUMBER
};

// Create sheet in "Sheets" folder (specifying the 2 columns to include in the sheet)
Sheet newSheet = smartsheet.SheetResources.CreateSheet(new Sheet
{
  Name = "newsheet",
  Columns = new Column[] { columnA, columnB }
}
);

// Specify properties of the first column
Column columnA = new Column()
  .setTitle("Favorite")
  .setType(ColumnType.CHECKBOX)
  .setSymbol(Symbol.STAR);

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

// Create sheet in "Sheets" folder (specifying the 2 columns to include in the sheet)
Sheet newSheet = new Sheet();
newSheet.setName("newsheet");
newSheet.setColumns(Arrays.asList(columnA, columnB));

smartsheet.sheetResources().createSheet(newSheet);

sheet_spec = smartsheet.models.Sheet({
  'name': 'newsheet',
  'columns': [{
      'title': 'Favorite',
      'type': 'CHECKBOX',
      'symbol': 'STAR'
    }, {
      'title': 'Primary Column',
      'primary': True,
      'type': 'TEXT_NUMBER'
    }
  ]
})
response = smartsheet_client.Home.create_sheet(sheet_spec)
new_sheet = response.result

body = {
  name: 'newsheet',
  columns: [
    {
      title: 'Favorite',
      type: 'CHECKBOX',
      symbol: 'STAR',
      width: 10
    },
    {
      title: 'Primary Column',
      type: 'TEXT_NUMBER',
      primary: true
    }
  ]
}

response = smartsheet.sheets.create(
  body: body
)
new_sheet = response[:result]

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "accessLevel": "OWNER",
        "columns": [{
      "id": 7960873114331012,
      "index": 0,
      "symbol": "STAR",
      "title": "Favorite",
      "type": "CHECKBOX"
            },
            {
      "id": 642523719853956,
      "index": 1,
      "primary": true,
      "title": "Primary Column",
      "type": "TEXT_NUMBER"
            }
        ],
        "id": 2331373580117892,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=0HHzeGnfHik-N13ZT8pU7g"
    }
}

POST /sheets

Creates a sheet from scratch in the user's Sheets folder (Home). For subfolders, use Create Sheet in Folder.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Sheet object, limited to the following attributes: name (required) - does not have to be unique columns (required) - array of Column objects, limited to the following attributes: primary (required) title (required), must be unique within the sheet type (required) autoNumberFormat (optional) options (optional) symbol (optional) systemColumnType (optional) width (optional)
Returns	Result object containing a Sheet object for newly created sheet, limited to the following attributes: accessLevel columns id name permalink
Access Scope	CREATE_SHEETS

Create Sheet in Folder

Example request: create sheet in folder

curl https://api.smartsheet.com/2.0/folders/{folderId}/sheets \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet","columns":[{"title":"Favorite","type":"CHECKBOX","symbol":"STAR"}, {"title":"Primary Column", "primary":true,"type":"TEXT_NUMBER"}]}'

// Specify sheet properties
var sheet = {
  "name": "newsheet",
  "columns": [
    {
      "title": "Favorite",
      "type": "CHECKBOX",
      "symbol": "STAR"
    },
    {
      "title": "Primary Column",
      "primary": true,
      "type": "TEXT_NUMBER"
    }
  ]
};

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

// Create sheet in folder
smartsheet.sheets.createSheetInFolder(options)
  .then(function(newSheet) {
    console.log(newSheet);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify properties of the first column
Column columnA = new Column
{
  Title = "Favorite",
  Primary = false,
  Type = ColumnType.CHECKBOX,
  Symbol = Symbol.STAR
};

// Specify properties of the second column
Column columnB = new Column
{
  Title = "Primary Column",
  Primary = true,
  Type = ColumnType.TEXT_NUMBER
};

// Create sheet in folder (specifying the 2 columns to include in the sheet)
Sheet newSheet = smartsheet.FolderResources.SheetResources.CreateSheet(
  3734419270854532,                   // long folderId
  new Sheet
    {
      Name = "new sheet title",
      Columns = new Column[] { columnA, columnB }
    }
);

// Specify properties of the first column
Column columnA = new Column()
  .setTitle("Favorite")
  .setType(ColumnType.CHECKBOX)
  .setSymbol(Symbol.STAR);

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

// Create sheet in folder (specifying the 2 columns to include in the sheet)
Sheet newSheet = new Sheet();
newSheet.setName("new sheet title");
newSheet.setColumns(Arrays.asList(columnA, columnB));

smartsheet.sheetResources().createSheetInFolder(
  3734419270854532L,  // long folderId
  newSheet
); 

sheet_spec = smartsheet.models.Sheet({
  'name': 'newsheet',
  'columns': [{
        'title': 'Favorite',
        'type': 'CHECKBOX',
        'symbol': 'STAR'
      }, {
        'title': 'Primary Column',
        'primary': True,
        'type': 'TEXT_NUMBER'
      }
  ]
})
response = smartsheet_client.Folders.create_sheet_in_folder(
  3734419270854532,       # folder_id
  sheet_spec)
new_sheet = response.result

body = {
  name: 'newsheet',
  columns: [
    {
      title: 'Favorite',
      type: 'CHECKBOX',
      symbol: 'STAR',
      width: 10
    },
    {
      title: 'Primary Column',
      type: 'TEXT_NUMBER',
      primary: true
    }
  ]
}

response = smartsheet.sheets.create_in_folder(
  folder_id: 3734419270854532,
  body: body
)
new_sheet = response[:result]

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "accessLevel": "OWNER",
        "columns": [{
      "id": 7960873114331012,
      "index": 0,
      "symbol": "STAR",
      "title": "Favorite",
      "type": "CHECKBOX"
            },
            {
      "id": 642523719853956,
      "index": 1,
      "primary": true,
      "title": "Primary Column",
      "type": "TEXT_NUMBER"
            }
        ],
        "id": 2331373580117892,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=0HHzeGnfHik-N13ZT8pU7g"
    }
}

POST /folders/{folderId}/sheets

Creates a sheet from scratch in the specified folder.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Sheet object, limited to the following attributes: name (required) - does not have to be unique columns (required) - array of Column objects, limited to the following attributes: primary (required) title (required), must be unique within the sheet type (required) autoNumberFormat (optional) options (optional) symbol (optional) systemColumnType (optional) width (optional)
Returns	Result object containing a Sheet object for newly created sheet, limited to the following attributes: accessLevel columns id name permalink
Access Scope	CREATE_SHEETS

Create Sheet in Workspace

Example request: create sheet in workspace

curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/sheets \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet","columns":[{"title":"Favorite","type":"CHECKBOX","symbol":"STAR"}, {"title":"Primary Column", "primary":true,"type":"TEXT_NUMBER"}]}'

// Specify sheet properties
var sheet = {
  "name": "newsheet",
  "columns": [
    {
      "title": "Favorite",
      "type": "CHECKBOX",
      "symbol": "STAR"
    },
    {
      "title": "Primary Column",
      "primary": true,
      "type": "TEXT_NUMBER"
    }
  ]
};

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

// Create sheet in workspace
smartsheet.sheets.createSheetInWorkspace(options)
  .then(function(newSheet) {
    console.log(newSheet);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify properties of the first column
Column columnA = new Column
{
  Title = "Favorite",
  Primary = false,
  Type = ColumnType.CHECKBOX,
  Symbol = Symbol.STAR
};

// Specify properties of the second column
Column columnB = new Column
{
  Title = "Primary Column",
  Primary = true,
  Type = ColumnType.TEXT_NUMBER
};

// Create sheet in workspace (specifying the 2 columns to include in the sheet)
Sheet newSheet = smartsheet.WorkspaceResources.SheetResources.CreateSheet(
  3734419270854532,                   // long workspaceId
  new Sheet
    {
      Name = "new sheet title",
      Columns = new Column[] { columnA, columnB }
    }
);

// Specify properties of the first column
Column columnA = new Column()
  .setTitle("Favorite")
  .setType(ColumnType.CHECKBOX)
  .setSymbol(Symbol.STAR);

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

// Create sheet in workspace (specifying the 2 columns to include in the sheet)
Sheet newSheet = new Sheet();
newSheet.setName("new sheet title");
newSheet.setColumns(Arrays.asList(columnA, columnB));

smartsheet.sheetResources().createSheetInWorkspace(
  3734419270854532L,    // long workspaceId
  newSheet
);

sheet_spec = smartsheet.models.Sheet({
  'name': 'newsheet',
  'columns': [{
      'title': 'Favorite',
      'type': 'CHECKBOX',
      'symbol': 'STAR'
    }, {
      'title': 'Primary Column',
      'primary': True,
      'type': 'TEXT_NUMBER'
    }
  ]
})

response = smartsheet_client.Workspaces.create_sheet_in_workspace(
  3734419270854532,           # workspace_id
  sheet_spec)
new_sheet = response.result

body = {
  name: 'newsheet',
  columns: [
    {
      title: 'Favorite',
      type: 'CHECKBOX',
      symbol: 'STAR',
      width: 10
    },
    {
      title: 'Primary Column',
      type: 'TEXT_NUMBER',
      primary: true
    }
  ]
}

response = smartsheet.sheets.create_in_workspace(
  workspace_id: 3734419270854532,
  body: body
)
new_sheet = response[:result]

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "accessLevel": "OWNER",
        "columns": [{
      "id": 7960873114331012,
      "index": 0,
      "symbol": "STAR",
      "title": "Favorite",
      "type": "CHECKBOX"
            },
            {
      "id": 642523719853956,
      "index": 1,
      "primary": true,
      "title": "Primary Column",
      "type": "TEXT_NUMBER"
            }
        ],
        "id": 2331373580117892,
        "name": "newsheet",
        "permalink": "https://app.smartsheet.com/b/home?lx=0HHzeGnfHik-N13ZT8pU7g"
    }
}

POST /workspaces/{workspaceId}/sheets

Creates a sheet from scratch at the top-level of the specified workspace. For subfolders, use Create Sheet in Folder.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Sheet object, limited to the following attributes: name (required) - does not have to be unique columns (required) - array of Column objects, limited to the following attributes: primary (required) title (required), must be unique within the sheet type (required) autoNumberFormat (optional) options (optional) symbol (optional) systemColumnType (optional) width (optional)
Returns	Result object containing a Sheet object for newly created sheet, limited to the following attributes: accessLevel columns id name permalink
Access Scope	CREATE_SHEETS

Create Sheet from Template

Create Sheet in "Sheets" Folder from Template

Example request: create sheet in "Sheets" folder from template

curl 'https://api.smartsheet.com/2.0/sheets?include=data,attachments,discussions' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet", "fromId": templateId}'

// Specify the directive
var sheet = {
  "fromId": 7679398137620356,
  "name": "newsheet"
  };

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

// Create sheet from template
smartsheet.sheets.createSheetFromExisting(options)
  .then(function(newSheet) {
    console.log(newSheet);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify name for the sheet and Id of the template
Sheet sheetSpecification = new Sheet
{
  Name = "new sheet title",
  FromId = 7679398137620356     // template Id
};

// Sample 1: Omit 'include' parameter
Sheet newSheet = smartsheet.SheetResources.CreateSheetFromTemplate(
  sheetSpecification,
  null                            // IEnumerable<TemplateInclusion> include
);

// Sample 2: Include ATTACHMENTS, DATA, and DISCUSSIONS
Sheet newSheet = smartsheet.SheetResources.CreateSheetFromTemplate(
  sheetSpecification,
  new TemplateInclusion[] {
    TemplateInclusion.ATTACHMENTS,
    TemplateInclusion.DATA,
    TemplateInclusion.DISCUSSIONS }
);

// Specify name for the sheet and Id of the template
Sheet sheet = new Sheet();
sheet.setFromId(7679398137620356L);     // long templateId
sheet.setName("newsheet");

// Sample 1: Omit 'include' parameter
Sheet results = smartsheet.sheetResources().createSheetFromTemplate(sheet,
  null                                    // EnumSet<SheetTemplateInclusion> includes
);

// Sample 2: Include ATTACHMENTS, DATA, and DISCUSSIONS
Sheet results = smartsheet.sheetResources().createSheetFromTemplate(
  sheet,
  EnumSet.of(
    SheetTemplateInclusion.ATTACHMENTS,
    SheetTemplateInclusion.DATA,
    SheetTemplateInclusion.DISCUSSIONS)
);

response = smartsheet_client.Home.create_sheet_from_template(
  smartsheet.models.Sheet({
    'name': 'newsheet',
    'from_id': 7679398137620356     # template_id
  })
)
new_sheet = response.result

body = {
  name: 'newsheet',
  from_id: 7679398137620356
}

response = smartsheet.sheets.create_from_template(
  body: body
)
new_sheet = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "accessLevel": "OWNER",
    "id": 7960873114331012,
    "name": "newsheet",
    "permalink": "https://app.smartsheet.com/b/home?lx=lbKEF1UakfTNJTZ5XkpxWg"
  }
}

POST /sheets

Creates a sheet in the user's Sheets folder (Home), from the specified template. For subfolders, use Create Sheet in Folder from Template.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of elements to copy from the template or sheet: attachments cellLinks data discussions forms
Request Body	Sheet object, limited to the following attributes: fromId (required) - the Id of the template from which to create the sheet name (required) - does not have to be unique
Returns	Result object containing a Sheet object for the newly created sheet, limited to the following attributes: accessLevel id name permalink
Access Scope	CREATE_SHEETS

Create Sheet in Folder from Template

Example request: create sheet in folder from template

curl 'https://api.smartsheet.com/2.0/folders/{folderId}/sheets?include=data,attachments,discussions' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet", "fromId": 7679398137620356}'

// Specify the directive
var sheet = {
  "name": "newsheet",
  "fromId": 7679398137620356
};

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

// Create sheet from template in the specified folder
smartsheet.sheets.createSheetFromExisting(options)
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify name for the sheet and Id of the template
Sheet sheetSpecification = new Sheet
{
  Name = "new sheet title",
  FromId = 7679398137620356     // template Id
};

// Sample 1: Omit 'include' parameter
Sheet newSheet = smartsheet.FolderResources.SheetResources.CreateSheetFromTemplate(
  3734419270854532,               // long folderId
  sheetSpecification,
  null                            // IEnumerable<TemplateInclusion> include
);

// Sample 2: Include ATTACHMENTS, DATA, and DISCUSSIONS
Sheet newSheet = smartsheet.FolderResources.SheetResources.CreateSheetFromTemplate(
  3734419270854532,               // long folderId
  sheetSpecification,
  new TemplateInclusion[] {
    TemplateInclusion.ATTACHMENTS,
    TemplateInclusion.DATA,
    TemplateInclusion.DISCUSSIONS }
);

// Specify name for the sheet and Id of the template
Sheet sheet = new Sheet();
sheet.setFromId(7679398137620356L);     // long templateId
sheet.setName("newsheet");

// Omit 'include' parameter
Sheet results = smartsheet.sheetResources().createSheetInFolderFromTemplate(
  3734419270854532L,                  // long folderId
  sheet,
  null                                // EnumSet<SheetTemplateInclusion> includes
);

// Include ATTACHMENTS, DATA, and DISCUSSIONS
Sheet results = smartsheet.sheetResources().createSheetInFolderFromTemplate(
  3734419270854532L,                 // long folderId
  sheet,
  EnumSet.of(
    SheetTemplateInclusion.ATTACHMENTS,
    SheetTemplateInclusion.DATA,
    SheetTemplateInclusion.DISCUSSIONS)
);  

response = smartsheet_client.Folders.create_sheet_in_folder_from_template(
  3734419270854532,                   # folder_id
  smartsheet.models.Sheet({
    'name': 'newsheet',
    'from_id': 7679398137620356       # template_id
  })
)

body = {
  name: 'newsheet',
  from_id: 7679398137620356
}

response = smartsheet.sheets.create_in_folder_from_template(
  folder_id: 3734419270854532,
  body: body
)
new_sheet = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "accessLevel": "OWNER",
    "id": 7960873114331012,
    "name": "newsheet",
    "permalink": "https://app.smartsheet.com/b/home?lx=lbKEF1UakfTNJTZ5XkpxWg"
  }
}

POST /folders/{folderId}/sheets

Creates a sheet in the specified folder, from the specified template.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of elements to copy from the template or sheet: attachments cellLinks data discussions forms
Request Body	Sheet object, limited to the following attributes: fromId (required) - the Id of the template from which to create the sheet name (required) - does not have to be unique
Returns	Result object containing a Sheet object for the newly created sheet, limited to the following attributes: accessLevel id name permalink
Access Scope	CREATE_SHEETS

Create Sheet in Workspace from Template

Example request: create sheet in workspace from template

curl 'https://api.smartsheet.com/2.0/workspaces/{workspaceId}/sheets?include=data,attachments,discussions' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"newsheet", "fromId": 7679398137620356}'

// Specify the directive
var sheet = {
  "fromId": 7679398137620356,
  "name": "newsheet"
  };

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

// Create sheet from template in the specified workspace
smartsheet.sheets.createSheetFromExisting(options)
  .then(function(newSheet) {
    console.log(newSheet);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify name for the sheet and Id of the template
Sheet sheetSpecification = new Sheet
{
  Name = "new sheet title",
  FromId = 7679398137620356     // template Id
};

// Sample 1: Omit 'include' parameter
Sheet newSheet = smartsheet.WorkspaceResources.SheetResources.CreateSheetFromTemplate(
  1656220827314052,               // long workspaceId
  sheetSpecification,
  null                            // IEnumerable<TemplateInclusion> include
);

// Sample 2: Include ATTACHMENTS, DATA, and DISCUSSIONS
Sheet newSheet = smartsheet.WorkspaceResources.SheetResources.CreateSheetFromTemplate(
  1656220827314052,               // long workspaceId
  sheetSpecification,
  new TemplateInclusion[] {
    TemplateInclusion.ATTACHMENTS,
    TemplateInclusion.DATA,
    TemplateInclusion.DISCUSSIONS }
);

// Specify name for the sheet and Id of the template
Sheet sheet = new Sheet();
sheet.setFromId(7679398137620356L);     // long templateId
sheet.setName("newsheet");

// Sample 1: Omit 'include' parameter
Sheet newSheet = smartsheet.sheetResources().createSheetInWorkspaceFromTemplate(
  1656220827314052L,                  // long workspaceId
  sheetSpecification,
  null                                // EnumSet<SheetTemplateInclusion> includes
);

// Sample 2: Include ATTACHMENTS, DATA, and DISCUSSIONS
Sheet newSheet = smartsheet.sheetResources().createSheetInWorkspaceFromTemplate(
  1656220827314052L,                 // long workspaceId
  sheetSpecification,
  EnumSet.of(
    SheetTemplateInclusion.ATTACHMENTS,
    SheetTemplateInclusion.DATA,
    SheetTemplateInclusion.DISCUSSIONS)
);  

response = smartsheet_client.Workspaces.create_sheet_in_workspace_from_template(
  1656220827314052,                   # workspace_id
  smartsheet.models.Sheet({
    'name': 'newsheet',
    'from_id': 7679398137620356     # template_id
  })
)

body = {
  name: 'newsheet',
  from_id: 7679398137620356
}

response = smartsheet.sheets.create_in_workspace_from_template(
  workspace_id: 1656220827314052,
  body: body
)
new_sheet = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "accessLevel": "OWNER",
    "id": 7960873114331012,
    "name": "newsheet",
    "permalink": "https://app.smartsheet.com/b/home?lx=lbKEF1UakfTNJTZ5XkpxWg"
  }
}

POST /workspaces/{workspaceId}/sheets

Creates a sheet at the top-level of the specified workspace, from the specified template. For subfolders, use Create Sheet in Folder from Template.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of elements to copy from the template or sheet: attachments cellLinks data discussions forms
Request Body	Sheet object, limited to the following attributes: fromId (required) - the Id of the template from which to create the sheet name (required) - does not have to be unique
Returns	Result object containing a Sheet object for the newly created sheet, limited to the following attributes: accessLevel id name permalink
Access Scope	CREATE_SHEETS

Delete Sheet

Example request: delete sheet

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

// Set options
var options = {
  id: 1531988831168388 // Id of Sheet
};

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

smartsheet.SheetResources.DeleteSheet(
  1531988831168388            // long sheetId
);

smartsheet.sheetResources().deleteSheet(
  1531988831168388L        // long sheetId
);

smartsheet_client.Sheets.delete_sheet(
  1531988831168388)       # sheet_id

smartsheet.sheets.delete(sheet_id: 1531988831168388)

Example response

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

DELETE /sheets/{sheetId}

Deletes the sheet specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	DELETE_SHEETS

Get Sheet Version

Example request: get sheet version

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

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

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

Integer version = smartsheet.SheetResources.GetSheetVersion(
  1531988831168388            // long sheetId
);

Integer version = smartsheet.sheetResources().getSheetVersion(
  1531988831168388L        // long sheetId
);

version = smartsheet_client.Sheets.get_sheet_version(
  1531988831168388)       # sheet_id

version = smartsheet.sheets.get_version(
  sheet_id: 1531988831168388
)

Example response

{
    "version": "23"
}

GET /sheets/{sheetId}/version

Gets the sheet version without loading the entire sheet.

The following actions increment sheet version:

• add/modify cell value
• add/modify discussion/comment
• add/modify row
• add/remove/update version attachment
• cell updated via cell link
• change formatting

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	A simple object with only a version attribute
Access Scope	READ_SHEETS

Get Sheet

Example request: get sheet

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

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

// Get sheet
smartsheet.sheets.getSheet(options)
    .then(function(sheetInfo) {
        console.log(sheetInfo);
    })
    .catch(function(error) {
        console.log(error);
    });

// Omit all parameters
Sheet sheet = smartsheet.SheetResources.GetSheet(
  4583173393803140,           // long sheetId
  null,                       // IEnumerable<SheetLevelInclusion> includes
  null,                       // IEnumerable<SheetLevelExclusion> excludes
  null,                       // IEnumerable<long> rowIds
  null,                       // IEnumerable<int> rowNumbers
  null,                       // IEnumerable<long> columnIds
  null,                       // Nullable<long> pageSize
  null                        // Nullable<long> page
);

// Omit all parameters
Sheet sheet = smartsheet.sheetResources().getSheet(
  4583173393803140L,      // long sheetId
  null,                   // EnumSet<SheetInclusion> includes    
  null,                   // EnumSet<ObjectExclusion> excludes
  null,                   // Set<Long> rowIds
  null,                   // Set<Integer> rowNumbers
  null,                   // Set<Long> columnIds
  null,                   // Integer pageSize
  null                    // Integer page
);

sheet = smartsheet_client.Sheets.get_sheet(
  4583173393803140)           # sheet_id

sheet = smartsheet.sheets.get(
  sheet_id: 4583173393803140
)

Example response

{
  "id": 4583173393803140,
  "name": "sheet 1",
  "version": 6,
  "totalRowCount": 240,
  "accessLevel": "OWNER",
  "effectiveAttachmentOptions": [
    "EVERNOTE",
    "GOOGLE_DRIVE",
    "EGNYTE",
    "FILE",
    "ONEDRIVE",
    "DROPBOX",
    "BOX_COM"
  ],
  "readOnly": true,
  "ganttEnabled": true,
  "dependenciesEnabled": true,
  "resourceManagementEnabled": true,
  "cellImageUploadEnabled": true,
  "userSettings": {
    "criticalPathEnabled": false,
    "displaySummaryTasks": true
  },
  "userPermissions": {
    "summaryPermissions": "ADMIN"
  },
  "workspace": {
    "id": 825898975642500,
    "name": "New Workspace"
  },
  "projectSettings": {
    "workingDays": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY"
    ],
    "nonWorkingDays": [],
    "lengthOfDay": 8
  },
  "hasSummaryFields": false,
  "permalink": "https://app.smartsheet.com/b/home?lx=pWNSDH9itjBXxBzFmyf-5w",
  "createdAt": "2018-09-24T20:27:57Z",
  "modifiedAt": "2018-09-26T20:45:08Z",
  "columns": [
    {
      "id": 4583173393803140,
      "version": 0,
      "index": 0,
      "primary": true,
      "title": "Primary Column",
      "type": "TEXT_NUMBER",
      "validation": false
    },
    {
      "id": 2331373580117892,
      "version": 0,
      "index": 1,
      "options": [
        "new",
        "in progress",
        "completed"
      ],
      "title": "status",
      "type": "PICKLIST",
      "validation": true
    }
  ],
  "rows": []
}

GET /sheets/{sheetId}

Gets the sheet specified in the URL. Returns the sheet, including rows, and optionally populated with discussion and attachment objects.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional): a comma-separated list of elements to include in the response. Supports all Row Include Flags with the following differences: attachments: includes the metadata for sheet-level and row-level attachments crossSheetReferences: includes the cross-sheet references discussions: includes sheet-level and row-level discussions filters: includes row.filteredOut attribute filterDefinitions: includes type of filter, operators used, and criteria format: includes column, row, and cell formatting ganttConfig: includes Gantt chart details objectValue -- when used in combination with a level query parameter, includes the email addresses for multi-contact data ownerInfo: includes the workspace and the owner's email address and user Id Also supports the source include flag, which adds the Source object indicating which report, sheet, Sight (aka dashboard), or template the sheet was created from, if any.
	exclude (optional): a comma-separated list of elements to not include in the response. filteredOutRows: excludes filtered out rows from response payload if a sheet filter is applied; includes total number of filtered rows include=format&exclude=nonexistentCells: excludes cells that have never contained data yet returns those cells if they have formatting or conditional formatting 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 nonexistentCells: excludes cells that have never contained any data
	columnIds (optional): a comma-separated list of column Ids. The response contains only the specified columns in the "columns" array, and individual rows' "cells" array only contains cells in the specified columns.
	filterId (optional): overrides the existing include={filters} parameter if both are supplied. Applies the given filter (if accessible by the calling user) and marks the affected rows as "filteredOut": true. Format is filterId={filterId}
	ifVersionAfter (optional): If version specified is still the current sheet version, then returns an abbreviated Sheet object with only the sheet version property. Otherwise, if the sheet has been modified, returns the complete Sheet object. Intended to allow clients with a cached copy to make sure they have the latest version.
	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).
	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.
	pageSize (optional): number of rows per page to include with the sheet. If neither pageSize nor page is specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100.
	rowIds (optional): a comma-separated list of row Ids on which to filter the rows included in the result
	rowNumbers (optional): a comma-separated list of row numbers on which to filter the rows included in the result. Non-existent row numbers are ignored.
Returns	Sheet object, populated according to the specified parameters
Access Scope	READ_SHEETS

Get Sheet as Excel / PDF / CSV

Example request: get sheet as Excel

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

var fs = require("fs")

// Set options
var options = {
  id: 169681224483716 // Id of Sheet
};

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

smartsheet.SheetResources.GetSheetAsExcel(
  4583173393803140,           // long sheetId
  outputStream
);

smartsheet.sheetResources().getSheetAsExcel(
  4583173393803140L,       // long sheetId
  outputStream
);

smartsheet_client.Sheets.get_sheet_as_excel(
  1531988831168388,           # sheet_id
  download_directory_path)

file_contents = smartsheet.sheets.get_as_excel(
  sheet_id: 1531988831168388
)

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 are written to "outputStream"

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

# download directory contains the downloaded Excel file

# See local file named "output.xlsx"

Example request: get sheet as PDF

curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}?paperSize=A1' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Accept: application/pdf" 
-o  output.pdf

var fs = require("fs")

// Set options
var options = {
  id: 169681224483716 // Id of Sheet
};

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

smartsheet.SheetResources.GetSheetAsPDF(
  4583173393803140,               // long sheetId
  outputStream,
  PaperSize.A1
);

smartsheet.sheetResources().getSheetAsPDF(
  4583173393803140L,       // long sheetId
  outputStream,
  PaperSize.A1
);

smartsheet_client.Sheets.get_sheet_as_pdf(
  1531988831168388,           # sheet_id
  download_directory_path,
  'A1')                       # paperSize

file_contents = smartsheet.sheets.get_as_pdf(
  sheet_id: 1531988831168388
)

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

Example response

# See local file named "output.pdf"

// See local file named "output.pdf"

// Contents of PDF file are written to "outputStream"

// Contents of PDF file are written to "outputStream"

# download directory contains the downloaded PDF file

# See local file named "output.pdf"

Example request: get sheet as CSV

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

var fs = require("fs")

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

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

smartsheet.SheetResources.GetSheetAsCSV(
  4583173393803140,               // long sheetId
  outputStream
);

smartsheet.sheetResources().getSheetAsCSV(
  4583173393803140L,       // long sheetId
  outputStream
);

smartsheet_client.Sheets.get_sheet_as_csv(
  1531988831168388,           # sheet_id
  download_directory_path)

file_contents = smartsheet.sheets.get_as_csv(
  sheet_id: 1531988831168388
)

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 are written to "outputStream"

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

# download directory contains the downloaded CSV file

# See local file named "output.csv"

GET /sheets/{sheetId}

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
	Accept -- must be set to one of the following values: application/pdf application/vnd.ms-excel text/csv
Parameters	paperSize (optional) -- applies to PDF only, must be one of: LETTER (default) LEGAL WIDE (same as 11x17) ARCHD A4 A3 A2 A1 A0
Returns	The file in either Excel, PDF, or CSV format.
Access Scope	READ_SHEETS

List Org Sheets

Example request: list org sheets

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

smartsheet.sheets.listOrganizationSheets()
  .then(function(sheetsList) {
    console.log(sheetsList)
  })
  .catch(function(error) {
    console.log(error);
  });

PaginatedResult<Sheet> sheets = smartsheet.UserResources.SheetResources.ListOrgSheets(
  null,               // PaginationParameters
  null                // Nullable<DateTime> modifiedSince
);

PagedResult<Sheet> sheets = smartsheet.userResources().listOrgSheets();

response = ss_client.Sheets.list_org_sheets()
sheets = response.data

response = smartsheet.sheets.list_for_org
sheets = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 1,
    "data": [
        {
            "id": 2894323533539204,
            "name": "New Sheet",
            "owner": "john.doe@smartsheet.com",
            "ownerId": 995857572373
        }
    ]
}

GET /users/sheets

Gets a summarized list of all sheets owned by the members of the organization account.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	modifiedSince (optional): when specified with a date and time value, response only includes the objects that are modified on or after the date and time specified. If you need to keep track of frequent changes, it may be more useful to use Get Sheet Version.
	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Sheet objects, limited to the following attributes: id name owner (email address) ownerId
Access Scope	ADMIN_USERS

List Sheets

Example request: list sheets

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

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

// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<Sheet> sheets = smartsheet.SheetResources.ListSheets(
  null,               // IEnumerable<SheetInclusion> includes
  null,               // PaginationParameters
  null                // Nullable<DateTime> modifiedSince
);

// Sample 2: Specify 'include' parameter with value of "SOURCE", and 'includeAll' parameter with value of 'true'
PaginatedResult<Sheet> sheets = smartsheet.SheetResources.ListSheets(
  new SheetInclusion[] { SheetInclusion.SOURCE },
  new PaginationParameters(
    true,           // includeAll
    null,           // int pageSize
    null)           // int page
);

// Sample 1: Omit 'include' parameter and pagination parameters
PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(
  null,           // EnumSet<SourceInclusion> includes
  null,           // PaginationParameters
  null            // Date modifiedSince
);

// Sample 2: Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters()
  .setIncludeAll(true);

// Specify 'include' parameter with value of "SOURCE", and 'includeAll' parameter with value of 'true'
PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(EnumSet.of(SourceInclusion.SOURCE), parameters, modifiedSince);

response = smartsheet_client.Sheets.list_sheets(include_all=True)
sheets = response.data

# Sample 1: Omit 'includeAll' parameter
response = smartsheet.sheets.list
sheets = response[:data]

# Sample 2: Specify 'includeAll' with a value of 'true'
response = smartsheet.sheets.list(params: {includeAll:true })
sheets = response

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "accessLevel": "OWNER",
            "id": 4583173393803140,
        "name": "sheet 1",
        "version": 5,
            "permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJesvSHCQ",
        "createdAt": "2015-06-05T20:05:29Z",
        "modifiedAt": "2015-06-05T20:05:43Z"
        },
        {
            "accessLevel": "OWNER",
            "id": 2331373580117892,
        "name": "sheet 2",
        "version": 86,
            "permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJrthEFTG",
        "createdAt": "2015-06-05T20:05:29Z",
        "modifiedAt": "2015-06-05T20:05:43Z"
        }
    ]
}

GET /sheets

Gets a list of all sheets that the user has access to in alphabetical order by name. The list contains an abbreviated Sheet object for each sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of optional elements to include in the response: sheetVersion - current version number of each sheet, should not be combined with pagination source - the Source object for any report, sheet, Sight (aka dashboard), or template that was created from another report, sheet, Sight, or template, if any
	modifiedSince (optional): when specified with a date and time value, response only includes the objects that are modified on or after the date and time specified. If you need to keep track of frequent changes, it may be more useful to use Get Sheet Version.
	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Sheet objects limited to the following attributes: id accessLevel createdAt modifiedAt name permalink source (included only if source is specified with the include parameter)
Access Scope	READ_SHEETS

Move Sheet

Example request: move sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/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 = {
  sheetId: 4583173393803140,
  body: body
};

// Move sheet
smartsheet.sheets.moveSheet(options)
  .then(function(movedSheet) {
    console.log(movedSheet);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination {
  DestinationId = 7960873114331012,           // long destinationFolderId
  DestinationType = DestinationType.FOLDER,
};

// Move sheet
Sheet sheet = smartsheet.SheetResources.MoveSheet(
  4583173393803140,                           // long sheetId
  destination
);

// Specify destination
ContainerDestination destination = new ContainerDestination();
destination.setDestinationType(DestinationType.FOLDER)
  .setDestinationId(7960873114331012L);

// Move sheet
Sheet sheet = smartsheet.sheetResources().moveSheet(
  4583173393803140L,                         // long sheetId
  destination
);

sheet = smartsheet_client.Sheets.move_sheet(
  4583173393803140,                       # sheet_id
  smartsheet.models.ContainerDestination({
    'destination_type': 'folder',       # folder, workspace, or home
    'destination_id': 7960873114331012  # folder_id
  })
)

body = {
  destination_type: 'folder',
  destination_id: 7960873114331012
}

sheet = smartsheet.sheets.move(
  sheet_id: 4583173393803140,
  body: body
)

Example response

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

POST /sheets/{sheetId}/move

Moves the specified sheet to a new location.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	ContainerDestination object, limited to the following required attributes: destinationId destinationType
Returns	Result object containing a Sheet object for the moved sheet, limited to the following attributes: id accessLevel name permalink
Access Scope	CREATE_SHEETS

Publish Sheet

Get Sheet Publish Status

Example request: get sheet publish status

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

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

// Get sheet publish status
smartsheet.sheets.getPublishStatus(options)
    .then(function(status) {
        console.log(status);
    })
    .catch(function(error) {
        console.log(error);
    });

SheetPublish status = smartsheet.SheetResources.GetPublishStatus(
  4583173393803140            // long sheetId
);

SheetPublish status = smartsheet.sheetResources().getPublishStatus(
  4583173393803140L,       // long sheetId
);

response = smartsheet_client.Sheets.get_publish_status(
  4583173393803140)       # sheet_id
status = response.result
# status is a smartsheet.models.SheetPublish object

status = smartsheet.sheets.get_publish_status(
  sheet_id: 4583173393803140
)

Example response

{
    "readOnlyLiteEnabled": false,
    "readOnlyFullEnabled": true,
    "readWriteEnabled": false,
    "icalEnabled": false,
    "readOnlyFullAccessibleBy": "ALL",
    "readOnlyFullUrl": "https://publish.smartsheet.com/6d35fa6c99334d4892f9591cf6065"
}

GET /sheets/{sheetId}/publish

Gets the sheet's 'Publish' settings.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	SheetPublish object
Access Scope	READ_SHEETS

Set Sheet Publish Status

Example request: set sheet publish status

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/publish \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"readOnlyLiteEnabled": true,"readOnlyFullEnabled": false,"readWriteEnabled": false,"icalEnabled": false}'

// Specify publish status
var publishStatus = {
  "readOnlyLiteEnabled": true,
  "readOnlyFullEnabled": false,
  "readWriteEnabled": false,
  "icalEnabled": false
};

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

// Set publish status
smartsheet.sheets.setPublishStatus(options)
    .then(function(updatedStatus) {
        console.log(updatedStatus);
    })
    .catch(function(error) {
        console.log(error);
    });

// Specify sheet publish status properties
SheetPublish publishSpecification = new SheetPublish
{
  ReadOnlyLiteEnabled = true,
  ReadOnlyFullEnabled = false,
  ReadWriteEnabled = false,
  IcalEnabled = false
};

// Set sheet publish status
SheetPublish updatedStatus = smartsheet.SheetResources.UpdatePublishStatus(
  4583614634583940,       // long sheetId
  publishSpecification
);

// Specify sheet publish status properties
SheetPublish publishSpecification = new SheetPublish()
  .setIcalEnabled(false)
  .setReadOnlyFullEnabled(false)
  .setReadWriteEnabled(false)
  .setReadOnlyLiteEnabled(true);

// Set sheet publish status
SheetPublish updatedStatus = smartsheet.sheetResources().updatePublishStatus(
  4583614634583940L,       // long sheetId
  publishSpecification
);

# With the Python SDK, if fewer than all four flags are set, current status is retrieved and merged with the flags that _are_ set with this method call.

updated_status = smartsheet_client.Sheets.set_publish_status(
  4583173393803140,       # sheet_id
  smartsheet.models.SheetPublish({
    'read_only_lite_enabled': True
  })
)

body = {
  read_only_lite_enabled: true,
  read_only_full_enabled: true,
  read_only_full_accessible_by: 'ALL',
  read_write_enabled: true,
  read_write_accessible_by: 'ORG',
  ical_enabled: true
}

status = smartsheet.sheets.set_publish_status(
  sheet_id: 4583173393803140,
  body: body
)

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "icalEnabled": false,
    "readOnlyFullEnabled": false,
    "readOnlyLiteEnabled": true,
    "readOnlyLiteUrl": "http://publish.smartsheet.com/9862638d9c444014b5d7a114d436e99d",
    "readWriteEnabled": false
  }
}

PUT /sheets/{sheetId}/publish

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	SheetPublish object
Returns	Result object containing a SheetPublish object
Access Scope	ADMIN_SHEETS

Search Sheet

Example request: search sheet

curl 'https://api.smartsheet.com/2.0/search/sheets/{sheetId}?query=stuff' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  sheetId: 1888207043356548,
  queryParameters: {
    query: "stuff"
  }
};

// Search sheet
smartsheet.search.searchSheet(options)
  .then(function (data) {
    console.log(data);
  })
  .catch(function (error) {
    console.log(error);
  });

// Set search criteria
string query = "stuff";

// Search sheet
SearchResult results = smartsheet.SearchResources.SearchSheet(
  9283173393803140,       // long sheetId
  query                   // string
);

// Set search criteria
string query = "stuff";

// Search sheet
SearchResult results = smartsheet.searchResources().searchSheet(
  9283173393803140L,       // long sheetId
  query
);

# Set search criteria
query = 'stuff'

# Search sheet
response = ss_client.Search.search_sheet(
  9283173393803140,       # sheet_id
  query)
# response is a ss_client.models.SearchResult object

response = smartsheet.search.search_sheet(
  query: 'stuff',
  sheet_id: 9283173393803140
)

Example response

{
  "results": [
    {
      "contextData": [
        "Discussion 1"
      ],
      "objectId": 1888207043356548,
      "objectType": "discussion",
      "parentObjectId": 7141187195824004,
      "parentObjectName": "Sheet 1",
      "parentObjectType": "sheet",
      "text": "discussion stuff goes here"
    }
  ],
  "totalCount": 1
}

GET /search/sheets/{sheetId}

Searches a sheet for the specified text.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	query (required): Text with which to perform the search. Use double-quotes for an exact search.
Returns	SearchResult object that contains a maximum of 100 SearchResultem objects
Access Scope	READ_SHEETS

Send Sheet via Email

Example request: send sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/emails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sendTo" : [{"email": "john.doe@smartsheet.com"}, {"groupId": 2258118617917316}], "subject": "Check these rows out!", "message": "Here is the Sheet I mentioned in our meeting.", "ccMe": false, "format": "PDF", "formatDetails": {"paperSize": "A4"}}'

// Configure email
var email = {
  "sendTo": [
    {
      "email": "john.doe@smartsheet.com"
    },
    {
      "groupId": 2258118617917316
    }
  ],
  "subject": "Check these rows out!",
  "message": "Here are the rows I mentioned in our meeting",
  "ccMe": false,
  "format": "PDF",
  "formatDetails": {
    "paperSize": "A4"
  }
};

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

// Send sheet via email
smartsheet.sheets.sendSheetViaEmail(options)
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify recipients
Recipient[] recipients = new Recipient[] {
  new Recipient { Email = "john.doe@smartsheet.com" },
  new Recipient { GroupId = 2258118617917316 }
};

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

// Send sheet via email
smartsheet.SheetResources.SendSheet(4293147074291588, sheetEmail);      // sheetId

// Specify individual recipient
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder()
  .setEmail("john.doe@smartsheet.com")
  .build();

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

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

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

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

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

response = ss_client.Sheets.send_sheet(
  4293147074291588,           # sheet_id
  ss_client.models.SheetEmail({
    'send_to': [
      ss_client.models.Recipient({'email': 'john.doe@smartsheet.com'}),
      ss_client.models.Recipient({'group_id': 2258118617917316})
    ],
    'subject': 'Check these rows out!',
    'message': 'Here are the rows I mentioned in our meeting.',
    'cc_me': False,
    'format': 'PDF',
    'format_details': ss_client.models.FormatDetails({
      'paper_size': 'A4'
    })
  })
)

# Configure email
body = {
  send_to: [
    {
      email: 'john.doe@smartsheet.com'
    },
    {
      group_id: 3051008235464580
    }
  ],
  subject: 'Check these rows out!',
  message: 'Here are the rows I mentioned in our meeting',
  cc_me: false,
  format: 'PDF',
  format_details: {
    paper_size: 'LEGAL'
  }
}

# Send sheet
response = smartsheet.sheets.send_via_email(
  sheet_id: 3294745817573252,
  body: body
)

Example response

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

POST /sheets/{sheetId}/emails

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

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	SheetEmail object
Returns	Result object
Access Scope	SHARE_SHEETS

Send Update Request

For details about sending update requests, see Create Update Request.

Share Sheet

For details about sheet sharing, see Sheet Sharing.

Sheet Summary

A sheet summary allows users to define, organize, and report on custom project and business metadata. Sheet summary is only available to customers with business or enterprise plans.

Add Image to Sheet Summary

Example request: add image to sheet summary

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields/{fieldId}/images?altText=my%20image \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: image/jpeg" \
-H 'Content-Disposition: attachment; filename="picture.jpg"' \
-X POST \
--data-binary @picture.jpg

var options = {
  sheetId: 1421228469708676,
  fieldId: 5629723890335892,
  path: 'C:/dog.jpg',
  fileName: 'dog.jpg'
};

smartsheet.sheets.addSummaryFieldImage(options)
  .then(function(summary) {
    console.log(summary);
  }).catch(function(error) {
    console.log(error);
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

# Sample  1: Add image 
file = File.new('C:\picture.jpg')
smartsheet.sheets.summaries.add_image(
  sheet_id: 1421228469708676,
  field_id: 5629723890335892,
  file: file,
  filename: 'picture.jpg',
  file_length: file.size,
  content_type: 'image/jpeg'
)

# Sample 2: Add image from path
smartsheet.sheets.summaries.add_image_from_path(
  sheet_id: 1421228469708676,
  field_id: 5629723890335892,
  path: 'C:\picture.jpg',
  filename: 'picture.jpg',
  content_type: 'image/jpeg'
)

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "id": 5629723890335892,
    "index": 1,
    "title": "Author",
    "type": "CONTACT_LIST",
    "locked": false,
    "lockedForUser": false,
    "objectValue": "my image",
    "formula": "=SYS_CELLIMAGE(\"my image\",\"H4F4Ksmk2sa3RuNv9l8FSZ\",325,284,\"picture.jpg\")",
    "image": {
      "id": "H4F4Ksmk2sa3RuNv9l8FSZ",
      "height": 325,
      "width": 284,
      "altText": "my image"
    },
    "createdAt": "2018-07-19T22:00:43Z",
    "modifiedAt": "2018-07-30T22:55:22Z"
  },
  "version": 50
}

POST /sheets/{sheetId}/summary/fields/{fieldId}/images

Adds an image to the summary field.

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

Add Summary Fields

Example request: add summary fields

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{ \
    "type": "TEXT_NUMBER", \
    "objectValue": "Sally Smart", \
    "index": 2, \
    "title": "Author" \
}]'

var options = {
  sheetId: 1421228469708676,
  body: [{
    type: 'TEXT_NUMBER',
    objectValue: 'Sally Smart',
    index: 2,
    title: 'Author'
  }]
};

smartsheet.sheets.addSummaryFields(options)
  .then(function(summary) {
    console.log(summary);
  }).catch(function(error) {
    console.log(error);
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

smartsheet.sheets.summaries.add_fields(
  sheet_id: 1421228469708676,
  body: [{
    type: 'TEXT_NUMBER',
    objectValue: 'Sally Smart',
    index: 2,
    title: 'Author'
  }]
)

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": [
    {
      "id": 8022355336292228,
      "index": 1,
      "title": "Author",
      "type": "TEXT_NUMBER",
      "locked": false,
      "lockedForUser": false,
      "objectValue": "Sally Smart",
      "displayValue": "Sally Smart",
      "createdAt": "2018-07-30T23:21:12Z",
      "modifiedAt": "2018-07-30T23:21:12Z"
    }
  ],
  "version": 52
}

POST /sheets/{sheetId}/summary/fields

Creates one or more summary fields for the specified sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Request Body	Array of SummaryField objects
Parameters	(Optional) renameIfConflict: Set to true if you want to override the requirement for unique summary field names. Repeated names will be adjusted by appending "(1)" or similar after the field name.
Returns	Array of SheetSummary objects
Access Scope	ADMIN_SHEETS

Delete Summary Fields

Example request: delete summary fields

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields?ids={fieldId1},{fieldId2},{fieldId3} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

var options = {
  sheetId: 1421228469708676,
  queryParameters: {
    ids: '207098194749316',
    '100091196549967',
    '450360473006272'
  }
};

smartsheet.sheets.deleteSummaryFields(options)
  .then(function(summary) {
    console.log(summary);
  }).catch(function(error) {
    console.log(error);
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

smartsheet.sheets.summaries.delete_fields(
  sheet_id: 1421228469708676,
  params: { ids: '207098194749316', '100091196549967', '450360473006272' }
)

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": [
    207098194749316,
    100091196549967,
    450360473006272
  ],
  "version": 51
}

DELETE /sheets/{sheetId}/summary/fields?ids={fieldId1},{fieldId2},{fieldId3}

Deletes summary fields from the specified sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	(Optional) ignoreSummaryFieldsNotFound: If true, the operation will succeed even if some fieldIds are not found.
Returns	Result object containing fieldIds corresponding to all summary fields that were successfully deleted.
Access Scope	ADMIN_SHEETS

Get Sheet Summary

Example request: get sheet summary

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary?include=writerInfo \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

var options = {
  sheetId: 1421228469708676
};

smartsheet.sheets.getSummary(options)
  .then(function(summary) {
    console.log(summary);
  })
  .catch(function(error) {
    console.log(error);
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

smartsheet.sheets.summaries.get(sheet_id: 1421228469708676)

Example response

{
  "fields": [
    {
      "id": 5629723890335892,
      "index": 0,
      "title": "Owner",
      "type": "CONTACT_LIST",
      "locked": false,
      "lockedForUser": false,
      "objectValue": {
        "objectType": "CONTACT",
        "email": "jane.roe@smartsheet.com",
        "name": "Jane Roe",
        "imageId": "u!1!8ljfd7w9-aY!AxDzH0wWv1Y!y9VvAgUOFdg"
      },
      "displayValue": "Jane Roe",
      "createdBy": {
        "name": "John Doe",
        "email": "john.doe@smartsheet.com"
      },
      "createdAt": "2018-07-19T22:00:43Z",
      "modifiedBy": {
        "name": "Sebastian Overwatch",
        "email": "sebastian.overwatch@smartsheet.com"
      },
      "modifiedAt": "2018-07-19T22:00:43Z"
    }
  ]
}

GET /sheets/{sheetId}/summary

Returns object containing array of summary fields.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of elements to include in the response. format: includes format info for cells, rows, and summary fields writerInfo: includes createdBy and modifiedBy attributes for rows and summary fields
	exclude (optional) -- a comma-separated list of elements to not include in the response. displayValue: excludes displayValue info for cells, rows, and summary fields image: excludes image attributes for cells and summary fields imageAltText: excludes alt text for cells and summary fields
Returns	SheetSummary object containing an array of SummaryField objects
Access Scope	READ_SHEETS

Get Summary Fields

Example request: get summary fields

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

var options = {
  sheetId: 1421228469708676
};

smartsheet.sheets.getSummaryFields(options)
  .then(function(summary) {
    console.log(summary);
  })
  .catch(function(error) {
    console.log(error);
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

smartsheet.sheets.summaries.get_fields(sheet_id: 1421228469708676)

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
  "data": [
    {
      "id": 5629723890335892,
      "index": 0,
      "title": "Owner",
      "type": "CONTACT_LIST",
      "locked": false,
      "lockedForUser": false,
      "objectValue": {
        "objectType": "CONTACT",
        "email": "jane.roe@smartsheet.com",
        "name": "Jane Roe",
        "imageId": "u!1!8ljfd7w9-aY!AxDzH0wWv1Y!y9VvAgUOFdg"
      },
      "displayValue": "Jane Roe",
      "createdAt": "2018-07-19T22:00:43Z",
      "modifiedAt": "2018-07-19T22:00:43Z"
    }
  ]
}

GET /sheets/{sheetId}/summary/fields

Returns object containing array of summary fields. Allows for pagination of results.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional) -- a comma-separated list of elements to include in the response. format: includes format info for cells, rows, and summary fields writerInfo: includes createdBy and modifiedBy attributes for rows and summary fields
	exclude (optional) -- a comma-separated list of elements to not include in the response. displayValue: excludes displayValue info for cells, rows, and summary fields image: excludes image attributes for cells and summary fields imageAltText: excludes alt text for cells and summary fields
	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	SheetSummary object containing an array of SummaryField objects
Access Scope	READ_SHEETS

Update Summary Fields

Example request: update summary fields

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '[{ \
    "id": 5629723890335892, \
    "type": "CONTACT_LIST", \
    "objectValue": { \
        "objectType": "CONTACT", \
        "email": "jane.roe@smartsheet.com", \
        "name": "Jane Roe" \
    }, \
    "index": 2, \
    "title": "Author" \
}]'

var options = {
  sheetId: 1421228469708676,
  body: [{
    id: 5629723890335892,
    objectValue: 'Accepted'
  }]
};

smartsheet.sheets.updateSummaryFields(options)
  .then(function(summary) {
    console.log(summary);
  }).catch(function(error) {
    console.log(error);
  });

// Not yet implemented

// Not yet implemented

# Not yet implemented

smartsheet.sheets.summaries.update_fields(
  sheet_id: 1421228469708676,
  body: [{
    id: 5629723890335892,
    objectValue: 'Accepted'
  }]
)

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": [
    {
      "id": 5629723890335892,
      "index": 1,
      "title": "Author",
      "type": "CONTACT_LIST",
      "locked": false,
      "lockedForUser": false,
      "objectValue": {
        "objectType": "CONTACT",
        "email": "jane.roe@smartsheet.com",
        "name": "Jane Roe"
      },
      "displayValue": "Jane Roe",
      "createdAt": "2018-07-19T22:00:43Z",
      "modifiedAt": "2018-07-30T22:26:13Z"
    }
  ],
  "version": 49
}

PUT /sheets/{sheetId}/summary/fields

Updates the summary fields for the given sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Request Body	Array of SummaryField objects
Parameters	(Optional) renameIfConflict: Set to true if you want to override the requirement for unique summary field names. Repeated names will be adjusted by appending "(1)" or similar after the field name.
Returns	Array of SheetSummary objects
Access Scope	ADMIN_SHEETS

Sort Rows in Sheet

Example request: sort rows in sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/sort \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"sortCriteria": [{"columnId": 4583173393803140, "direction": "DESCENDING"}]}'

// Specify sort criteria
var body = {
  sortCriteria: [
    {
      columnId: 4583173393803140,
      direction: "DESCENDING"
    }
  ]
};

// Sort rows
smartsheet.sheets.sortRowsInSheet({sheetId: 9283173393803140, 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

sort_specifier = smartsheet.models.SortSpecifier({
    'sort_criteria': [smartsheet.models.SortCriterion({
        'column_id': 4583173393803140,
        'direction': 'DESCENDING'
    })]
})
sheet = smartsheet_client.Sheets.sort_sheet(9283173393803140, sort_specifier)

smartsheet.sheets.rows.sort(
  sheet_id: 9283173393803140,
  body: {
    sort_criteria: [
      {
        column_id: 4583173393803140,
        direction: 'DESCENDING'
      }
    ]
  }
)

Example response

{
  "accessLevel": "OWNER",
  "projectSettings": {
    "workingDays": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY"
    ],
    "nonWorkingDays": [
      "2018-01-01"
    ],
    "lengthOfDay": 6
  },
  "columns": [
    {
      "id": 4583173393803140,
      "version": 0,
      "index": 0,
      "primary": true,
      "title": "Primary Column",
      "type": "TEXT_NUMBER",
      "validation": false
    },
    {
      "id": 2331373580117892,
      "version": 0,
      "index": 1,
      "options": [
        "new",
        "in progress",
        "completed"
      ],
      "title": "status",
      "type": "PICKLIST",
      "validation": true
    }
  ],
  "createdAt": "2012-07-24T18:22:29-07:00",
  "id": 4583173393803140,
  "modifiedAt": "2012-07-24T18:30:52-07:00",
  "name": "sheet 1",
  "permalink": "https://app.smartsheet.com/b/home?lx=pWNSDH9itjBXxBzFmyf-5w",
  "rows": []
}

POST /sheets/{sheetId}/sort

Sorts the rows of a sheet, either in ascending or descending order.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Request Body	SortSpecifier with the following attribute: sortCriteria -- SortCriterion array in priority order. Specifies sort order.
Parameters	(Optional) Any of the relevant parameters or query parameters listed for Get Sheet
Returns	Sheet object, populated according to the specified parameters
Access Scope	WRITE_SHEETS

Update Sheet

Example request: update sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name":"New Sheet Name", 
  "userSettings": {"criticalPathEnabled": true}, 
  "projectSettings":{ 
    "workingDays": ["MONDAY", "TUESDAY", "WEDNESDAY"], 
    "nonWorkingDays": ["2018-01-01"], 
    "lengthOfDay": 6 
  } \
}'

// Specify updated sheet properties
var sheet = {
  "name": "New Sheet Name",
  "userSettings": {
    "criticalPathEnabled": true,
  }
};

// Set options
var options = {
  id: 7960873114331012, // Id of Sheet
  body: sheet
  };

// Update sheet
smartsheet.sheets.updateSheet(options)
  .then(function(updatedSheet) {
    console.log(updatedSheet);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify updated sheet properties
Sheet sheetSpecification = new Sheet
{
  Id = 4583173393803140,
  Name = "New Sheet Name",
  UserSettings = new SheetUserSettings{CriticalPathEnabled = true}
};

// Update sheet
Sheet updatedSheet = smartsheet.SheetResources.UpdateSheet(sheetSpecification);

// Specify updated sheet properties
Sheet sheetSpecification = new Sheet();
sheetSpecification.setUserSettings(new SheetUserSettings().setCriticalPathEnabled(true))
  .setName("New Sheet Name")
  .setId(7960873114331012L);

// Update sheet
Sheet updatedSheet = smartsheet.sheetResources().updateSheet(sheetSpecification);

updated_sheet = smartsheet_client.Sheets.update_sheet(
  4583173393803140,       # sheet_id
  smartsheet.models.Sheet({
    'name': 'New Sheet Name',
    'user_settings': smartsheet.models.SheetUserSettings({
      'critical_path_enabled': True
    })
  })
)

body = {
  name: 'New Sheet Name',
  user_settings: {
    critical_path_enabled: true,
    display_summary_tasks: false
  },
  project_settings: {
    working_days: ['MONDAY', 'TUESDAY', 'WEDNESDAY'],
    non_working_days: ['2018-01-01'],
    length_of_day: 6
  }
}

response = smartsheet.sheets.update(
  sheet_id: 4583173393803140,
  body: body
)
updated_sheet = response

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "id": 7960873114331012,
    "name": "New Sheet Name",
    "accessLevel": "OWNER",
    "userSettings": {
      "criticalPathEnabled": true
    },
    "projectSettings": {
      "workingDays": ["MONDAY", "TUESDAY", "WEDNESDAY"]
      "nonWorkingDays": ["2018-01-01"]
      "lengthOfDay": 6
    },
    "permalink": "https://app.smartsheet.com/b/home?lx=RE8LkzA48kPRWTzcgEYOga"
  }
}

PUT /sheets/{sheetId}

Updates the sheet specified in the URL.

To modify sheet contents, see Add Rows, Update Rows, Add Columns, and Update Column.

This operation can be used to update an individual user's sheet settings. If the request body contains only the userSettings attribute, this operation may be performed even if the user only has read-only access to the sheet (for example, the user has viewer permissions or the sheet is read-only).

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Sheet object limited to the following attributes: name (optional) projectSettings (optional): ProjectSettings object, containing at least one of the projectSettings attributes, for updating this sheet's project settings and dependencies. userSettings (optional): SheetUserSettings object for updating these user's settings for the sheet NOTE: Attributes not specified in projectSettings are not updated. If projectSettings.nonWorkingDays is specified as an empty array, all non-working days are removed from the project sheet.
Returns	Result object containing a Sheet object for the updated sheet
Access Scope	ADMIN_SHEETS

Related Items

A sheet is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

Sheet Attachments

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

Sheet Cells

For details about working with a sheet's cells, see Cells.

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

Sheet Columns

For details about working with a sheet's columns, see Columns.

Sheet Discussions

There are two ways to get discussion-related information for a sheet:

Operation	Returns
Get Sheet (with include parameter value discussions)	Response does not contain the comments that comprise each discussion.
List Discussions (with include parameter value comments)	Response contains the comments that comprise each discussion.

For more information about working with a sheet's discussions, see Discussions.

Sheet Rows

For details about working with a sheet's rows, see Rows.

Sights

Smartsheet Sights(TM) are a collection of widgets that can contain data from a variety of different data sources (for example, sheets, reports, or custom data). Sights are now called dashboards in the UI.

Objects

Sight Object

Example: Sight object

{
  "id": 2591554075418573,
  "name": "Test",
  "accessLevel": "OWNER",
  "columnCount": 6,
  "widgets": []
}

id	number	Sight Id
accessLevel	string	User's permissions on the Sight. Valid values: ADMIN OWNER VIEWER
backgroundColor	hex	The hex color, for instance #E6F5FE
columnCount	number	Number of columns that the Sight contains
createdAt	timestamp	Time of creation
favorite	Boolean	Indicates whether the user has marked the Sight as a favorite
modifiedAt	timestamp	Time of last modification
name	string	Sight name
permalink	string	URL that represents a direct link to the Sight in Smartsheet
source	source	A Source object indicating the Sight (aka dashboard) from which this Sight was created, if any
widgets	widget[]	Array of Widget objects
workspace	Workspace	A Workspace object, limited to only 2 attributes: id name NOTE: this attribute is only present if the Sight resides within a workspace.

SightPublish Object

readOnlyFullAccessibleBy	string	Indicates who can access the 'Read-Only Full' view of the published Sight: ALL -- available to anyone who has the link. ORG -- available only to members of the Sight owner's Smartsheet organization account. Only returned in a response if readOnlyFullEnabled = true.
readOnlyFullEnabled	Boolean	If true, a rich version of the Sight is published with the ability to use shortcuts and widget interactions.
readOnlyFullUrl	string	URL for 'Read-Only Full' view of the published Sight. Only returned in a response if readOnlyFullEnabled = true.

Widget Object

Example: Widget object

{
  "id": 3056651398234562,
  "type": "RICHTEXT",
  "contents": {
    "htmlContent": "<p>This is a test</p>"
  },
  "xPosition": 2,
  "yPosition": 0,
  "width": 2,
  "height": 4,
  "showTitleIcon": false,
  "titleFormat": ",,1,,,,,,,3,,,,,,",
  "version": 1
}

id	number	Widget Id
type	string	Type of widget. See table below to see how UI widget names map to type.
contents	WidgetContent object	Data that specifies the contents of the widget. NOTE: The type of WidgetContent object (and attributes within) depends on the value of widget.type.
height	number	Number of rows that the widget occupies on the Sight
showTitle	Boolean	True indicates that the client should display the widget title. NOTE: This is independent of the title string which may be null or empty.
showTitleIcon	Boolean	True indicates that the client should display the sheet icon in the widget title
title	string	Title of the widget
titleFormat	string	FormatDescriptor
version	int	Widget version number
viewMode	int	1 indicates content is centered. 2 indicates content is left aligned. Must use a query parameter of level=2 to see this information.
width	number	Number of columns that the widget occupies on the Sight
xPosition	number	X-coordinate of widget's position on the Sight
yPosition	number	Y-coordinate of widget's position on the Sight

UI widget name	type string	Object
Chart	CHART	ChartWidgetContent
Image	IMAGE	ImageWidgetContent
Metric	METRIC	CellLinkWidgetContent
Report	GRIDGANTT	ReportWidgetContent
Rich Text	RICHTEXT	RichTextWidgetContent
Shortcut	SHORTCUT	ShortcutWidgetContent
Title	TITLE	TitleWidgetContent
Web Content	WEBCONTENT	WebContentWidgetContent

CellLinkWidgetContent Object

sheetId	number	The Id of the sheet from which the cell data originates
cellData	CellDataItem[]	Array of CellDataItem objects
columns	Column[]	Array of Column objects
hyperlink	WidgetHyperlink	The widget has when clicked attribute set to that hyperlink (if present and non-null)

CellDataItem Object

columnId	number	Column Id for each item
rowId	number	Row Id for each item
sheetId	number	Sheet Id for each item
objectValue	A string, number, or a Boolean value	The type of data returned depends on the cell type and the data in the cell
cell	Cell	Cell object
dataSource	string	CELL
label	string	Label for the data point. This is either the column name or a user-provided string
labelFormat	string	formatDescriptor
order	integer	The display order for the CellDataItem
valueFormat	string	formatDescriptor

ChartWidgetContent Object

reportId	number	Report Id denoting container source, if applicable
sheetId	number	Sheet Id denoting container source, if applicable
axes	Axes[]	Array of Axes objects
hyperlink	WidgetHyperlink	The widget has when clicked attribute set to that hyperlink (if present and non-null)
includedColumnIds	includedColumnIds[]]	Array of columnIds if the range was selected through the UI
legend	string	The location in the widget where Smartsheet renders the legend, for example, RIGHT
selectionRanges	SelectionRange[]	If the source is a sheet
series	Series[]	Array of Series objects

ImageWidgetContent Object

privateId	string	The image private Id
fileName	string	Name of the image file
format	string	formatDescriptor
height	integer	Original height of the image in pixels
hyperlink	WidgetHyperlink	The widget has when clicked attribute set to that hyperlink (if present and non-null). Hyperlinks will have interactionType.
width	integer	Original width of the image in pixels

ReportWidgetContent Object

reportId	number	Report Id denoting container source
htmlContent	string	HTML snippet to render report
hyperlink	WidgetHyperlink	The widget has when clicked attribute set to that hyperlink (if present and non-null). Hyperlinks will have interactionType.

RichTextWidgetContent Object

html	string	The widget content as HTML The Rich Text widget supports the following subset of HTML tags and CSS Styles: HTML a - defines a hyperlink br - inserts a single line break li - defines a list item ol - defines an ordered list p - defines a paragraph ul - defines an unordered list span - defines a section in a document CSS color font-family font-size font-style font-weight text-align text-decoration

SelectionRange Object

sourceColumnId1	number	Defines beginning edge of range when specifying one or more columns.
sourceColumnId2	number	Defines ending edge of range when specifying one or more columns.
sourceRowId1	number	Defines beginning edge of range when specifying one or more rows.
sourceRowId2	number	Defines ending edge of range when specifying one or more rows.

ShortcutWidgetContent Object

shortcutData	ShortcutDataItem[]	Array of ShortcutDataItem objects

ShortcutDataItem Object

attachmentType	string	Attachment type (one of BOX_COM, DROPBOX, EGNYTE, EVERNOTE, FILE, GOOGLE_DRIVE, LINK, ONEDRIVE, or SMARTSHEET)
hyperlink	Hyperlink	Hyperlink object
label	string	Label for the data point
labelFormat	string	formatDescriptor
mimeType	string	MIME type if available for attachment type
order	integer	The display order for the ShortcutWidgetItem object

TitleWidgetContent Object

backgroundColor	hex	The hex color, for instance #E6F5FE
htmlContent	string	HTML snippet to render title

WebcontentWidgetContent Object

url	string	The URL

WidgetHyperlink Object

interactionType	string	Specifies what happens when a user clicks the widget. Valid values: DISTI_COPY -- a distribution link, only available if org has distribution links enabled NONE -- do nothing, no other attribute required SMARTSHEET_ITEM -- open a Smartsheet item that is not the SOURCE_SHEET, must also have one of the following: folderId reportId sheetId sightId workspaceId SOURCE_SHEET -- open the container where the widget data comes from, no other attribute required WEB -- launch the URL, must also have url attribute
folderId	number	If interactionType = SMARTSHEET_ITEM this is the folder to open
reportId	number	If interactionType = SMARTSHEET_ITEM this is the report to open
sheetId	number	If interactionType = SMARTSHEET_ITEM this is the sheet to open
sightId	number	If interactionType = SMARTSHEET_ITEM this is the Sight (aka dashboard) to open
url	string	If interactionType = WEB this is the URL to launch
workspaceId	number	If interactionType = SMARTSHEET_ITEM this is the workspace to open

Copy Sight

Example request: copy Sight

curl https://api.smartsheet.com/2.0/sights/{sightId}/copy \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"
-d '{ 
  "destinationType": "workspace", 
  "destinationId": 7960873114331012, 
  "newName": "newSightName" 
}' \
-X POST

// Specify new Sight properties
var body = {
  destinationType: "home",
  newName: "newSightName"
};

// Set options
var options = {
  sightId: 6327127650920324,
  body: body
};

// Copy Sight
smartsheet.sights.copySight(options)
  .then(function(copiedSight) {
    console.log(copiedSight);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination
{
  DestinationId = 3791509922310020,               // long destinationFolderId
  DestinationType = DestinationType.FOLDER,
  NewName = "newSightName"
};

// Copy Sight
Sight sight = smartsheet.SightResources.CopySight(
  6327127650920324,                               // long sightId
  destination
);

// Specify destination
ContainerDestination destination = new ContainerDestination()
  .setDestinationType(DestinationType.FOLDER)
  .setDestinationId(3791509922310020L)
  .setNewName("newSightName");

// Copy Sight
Sight sight = smartsheet.sightResources().copySight(
  6327127650920324L,                          // long sightId
  destination
);

new_sight = smartsheet_client.Sights.copy_sight(
  6327127650920324,                           # sight_id
  smartsheet.models.ContainerDestination({
    'destination_type': 'folder',           # folder, workspace, or home
    'destination_id': 3791509922310020,     # folder_id
    'new_name': 'newSightName'
  })
)

# Specify destination
body = {
  destination_type: 'folder',
  destination_id: 3791509922310020,
  new_name: 'newSightName'
}

# Copy Sight
new_sight = smartsheet.sights.copy(
  sight_id: 6327127650920324,
  body: body
)

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": 4583173393803140,
    "name": "newSightName",
    "accessLevel": "OWNER",
    "permalink": "https://app.smartsheet.com/b/home?lx=lB0JaOh6AX1wGwqxsQIMaA"
  }
}

POST /sights/{sightId}/copy

Creates a copy of the specified Sight.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	ContainerDestination object
Returns	Result object containing a Sight for the newly created Sight, limited to the following attributes: id accessLevel name permalink
Access Scope	CREATE_SIGHTS

Delete Sight

Example request: delete Sight

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

// Set options
var options = {
  sightId: 5363568917931908
};

// Delete Sight
smartsheet.sights.deleteSight(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.SightResources.DeleteSight(
  5077532685952900            // long sheetId
);

smartsheet.sightResources().deleteSight(
  3100061023397764L       // long sightId
);

smartsheet_client.Sights.delete_sight(3404239197235076)     # sight_id

smartsheet.sights.delete(
  sight_id: 6327127650920324
)

Example response

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

DELETE /sights/{sightId}

Deletes the Sight specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	DELETE_SIGHTS

Get Sight

Example request: get Sight

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

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

// Get Sight
smartsheet.sights.getSight(options)
  .then(function(sight) {
    console.log(sight);
  })
  .catch(function(error) {
    console.log(error);
  });

Sight sight = smartsheet.SightResources.GetSight(
  6327127650920324        // long sightId
);

Sight sight = smartsheet.sightResources().getSight(
  6327127650920324L       // long sightId
);

sight = smartsheet_client.Sights.get_sight(
  6327127650920324)     # sightId

sight = smartsheet.sights.get(
  sight_id: 6327127650920324
)

Example response

{
  "id": 2591554075418573,
  "name": "Test",
  "accessLevel": "OWNER",
  "columnCount": 6,
  "widgets": [
    {
      "id": 3056651398234562,
      "type": "RICHTEXT",
      "contents": {
        "htmlContent": "<p>This is a test</p>"
      },
      "xPosition": 2,
      "yPosition": 0,
      "width": 2,
      "height": 4,
      "showTitleIcon": false,
      "titleFormat": ",,1,,,,,,,3,,,,,,",
      "version": 1
    },
    {
      "id": 48092647672583496,
      "type": "SHORTCUT",
      "contents": {
        "shortcutData": [
          {
            "label": "Sight Data",
            "labelFormat": ",2,,,,,1,,1,,,,,,,",
            "hyperlink": {
              "url": "https://app.smartsheet.com/b/home?lx=m1O5qo7tpM1h23KFxYavIw",
              "sheetId": 692061146243972
            },
            "attachmentType": "SMARTSHEET",
            "order": 0
          }
        ]
      },
      "xPosition": 1,
      "yPosition": 0,
      "width": 1,
      "height": 1,
      "showTitleIcon": false,
      "titleFormat": ",,1,,,,,,,3,,,,,,",
      "version": 1
    }
  ]
}

GET /sights/{sightId}

Gets the specified Sight.

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 Sight that was created from another Sight, if any
	level (optional): allows you to specify whether you want to see data as text format for backwards compatibility or you want to see multi-contact data. Use level=0 or level=1 (default) for text or level=2 for multi-contact.
	objectValue (optional) -- when used in combination with a level query parameter, includes the email addresses for multi-contact data.
Returns	Sight object
Access Scope	READ_SIGHTS

List Sights

Example request: list Sights

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

smartsheet.sights.listSights()
  .then(function(sights) {
    console.log(sights.data);
  })
  .catch(function(error) {
    console.log(error);
  })

PaginatedResult<Sight> sights = smartsheet.SightResources.ListSights(
  null,       // PaginationParameters
  null        // Nullable<DateTime> modifiedSince
);

PagedResult<Sight> sights = smartsheet.sightResources().listSights(
  null,       // PaginationParameters
  null        // Date modifiedSince
);

response = smartsheet_client.Sights.list_sights(include_all=True)
sights = response.data

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

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
    {
      "id": 2331373580117892,
      "name": "Sales Sight",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJesvSHCQ",
      "createdAt": "2016-01-28T00:24:41Z",
      "modifiedAt": "2016-01-28T20:32:33Z"
    },
    {
      "id": 7397923160909700,
      "name": "Sight #2",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJrthEFTG",
      "createdAt": "2016-01-28T01:17:51Z",
      "modifiedAt": "2016-01-28T20:32:27Z"
    }
    ]
}

GET /sights

Gets a list of all Sights that the user has access to.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	modifiedSince (optional): when specified with a date and time value, response only includes the objects that are modified on or after the date and time specified. If you need to keep track of frequent changes, it may be more useful to use Get Sheet Version.
	This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns	IndexResult object containing an array of Sight objects limited to the following attributes: id accessLevel createdAt modifiedAt name permalink
Access Scope	READ_SIGHTS

Move Sight

Example request: move Sight

curl https://api.smartsheet.com/2.0/sights/{sightId}/move \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"
-d '{ 
  "destinationType": "folder", 
  "destinationId": workspace_or_folder_id 
}' \
-X POST

// Set destination
var body = {
  destinationType: "folder",
  destinationId: 8460057768683396
};

// Set options
var options = {
  sightId: 5077532685952900,
  body: body
};

// Move Sight
smartsheet.sights.moveSight(options)
  .then(function(movedSight) {
    console.log(movedSight);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify destination
ContainerDestination destination = new ContainerDestination
{
  DestinationId = 8460057768683396,               // long destinationFolderId
  DestinationType = DestinationType.FOLDER
};

// Move Sight
Sight sight = smartsheet.SightResources.MoveSight(
  5077532685952900,                               // long sightId
  destination
);

// Specify destination
ContainerDestination destination = new ContainerDestination()
  .setDestinationType(DestinationType.FOLDER)
  .setDestinationId(7960873114331012L);

// Move Sight
Sight sight = smartsheet.sightResources().moveSight(
  4583173393803140L,                          // long sightId
  destination
);

response = smartsheet_client.Sights.move_sight(
  5363568917931908,                           # sight_id
  smartsheet.models.ContainerDestination({
    'destination_type': 'folder',           # folder, workspace, or home
    'destination_id': 8460057768683396      # destination folder_id
  })
)

# Specify destination
body = {
  destination_type: 'folder',
  destination_id: 8460057768683396
}

# Move Sight
response = smartsheet.sights.move(
  sight_id: 5363568917931908,
  body: body
)
moved_sight = response[:result]

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": 4583173393803140,
    "name": "moved_Sight_name",
    "accessLevel": "OWNER",
    "permalink": "https://app.smartsheet.com/b/home?lx=lB0JaOh6AX1wGwqxsQIMaA"
  }
}

POST /sights/{sightId}/move

Moves the specified Sight to a new location.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	ContainerDestination object, limited to the following required attributes: destinationId destinationType
Returns	Result object containing a Sight object for the moved Sight, limited to the following attributes: id accessLevel name permalink
Access Scope	CREATE_SIGHTS

Publish Sight

Get Sight Publish Status

Example request: get Sight publish status

curl https://api.smartsheet.com/2.0/sights/{sightId}/publish \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  sightId: 970160971507588
};

// Get Sight publish status
smartsheet.sights.getSightPublishStatus(options)
  .then(function(status) {
    console.log(status);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// [todo]

status = smartsheet_client.Sights.get_publish_status(
  5363568917931908)       # sight_id

status = smartsheet.sights.get_publish_status(
  sight_id: 970160971507588
)

Example response

{
  "readOnlyFullEnabled": true,
  "readOnlyFullAccessibleBy": "ALL",
  "readOnlyFullUrl": "https://publish.smartsheet.com/6d35fa6c99334d4892f9591cf6065"
}

GET /sights/{sightId}/publish

Gets the Sight 'publish' settings.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	SightPublish object
Access Scope	READ_SIGHTS

Set Sight Publish Status

Example request: set Sight publish status

curl https://api.smartsheet.com/2.0/sights/{sightId}/publish \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
-H "Content-Type: application/json"
-X PUT
-d '{ 
  "readOnlyFullEnabled": true, 
  "readOnlyFullAccessibleBy": "ALL" 
}' \

// Specify property to change
var body = {
  readOnlyFullEnabled: false
};

// Set options
var options = {
  sightId: 5363568917931908,
  body: body
};

// Set Sight publish status
smartsheet.sights.setSightPublishStatus(options)
  .then(function(newStatus) {
    console.log(newStatus);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// [todo]

response = smartsheet_client.Sights.set_publish_status(
  5363568917931908,       # sight_id
  smartsheet.models.SightPublish({
    'read_only_full_enabled': True
  })
)

# Set options
body = {
  read_only_full_enabled: true,
  read_only_full_accessible_by: 'ALL'
}

# Set Sight publish status
response = smartsheet.sights.set_publish_status(
  sight_id: 5363568917931908,
  body: body
)
status = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "readOnlyFullEnabled": true,
    "readOnlyFullAccessibleBy": "ORG",
    "readOnlyFullUrl": "http://publish.smartsheet.com/9862638d9c444014b5d7a114d436e99d"
  }
}

PUT /sights/{sightId}/publish

Publishes or unpublishes a Sight.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	SightPublish object limited to the following attributes: readOnlyFullEnabled (required) readOnlyFullAccessibleBy (optional) - set to either ALL or ORG, when readOnlyFullEnabled=true. To publish the Sight, set readOnlyFullEnabled to true. To unpublish the Sight, set readOnlyFullEnabled to false.
Returns	Result object containing a SightPublish object
Access Scope	ADMIN_SIGHTS

Share Sight

For details about Sight sharing, see Sight Sharing.

Update Sight

Example request: update Sight

curl https://api.smartsheet.com/2.0/sights/{sightId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name": "New Sight Name"}'

// Set property to change
var body = {
  name: "New Sight Name"
};

// Set options
var options = {
  sightId: 5363568917931908,
  body: body
};

// Update Sight
smartsheet.sights.updateSight(options)
  .then(function(updatedSight) {
    console.log(updatedSight);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// [todo]

updated_sight = smartsheet_client.Sights.update_sight(
  5363568917931908,           # sight_id
  smartsheet.models.Sight({
    'name': 'New Sight Name'
  })
)

# Specify property to change
body = {
  name: 'New Sight Name'
}

# Update Sight
response = smartsheet.sights.update(
  sight_id: 5363568917931908,
  body: body
)
updated_sight = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "id": 5363568917931908,
    "name": "New Sight Name",
    "accessLevel": "OWNER",
    "permalink": "https://app.smartsheet.com/b/home?lx=rBU8QqUVPCJ3geRgl7L8yQ"
  }
}

PUT /sights/{sightId}

Updates (renames) the specified Sight.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Sight object limited to the following attribute: name (string)
Returns	Result object containing the updated Sight object
Access Scope	ADMIN_SIGHTS

Templates

A template can be used to create a sheet, as described in Create Sheet from Template.

Objects

Template Object

Example: Template object

{
    "id": 3457273486960516,
    "name": "template 1",
    "accessLevel": "OWNER",
    "description": "This is template 1"
}

id	number	Template Id
type	string	Type of the template. One of sheet or report Only applicable to public templates
accessLevel	string	User's permissions on the template
blank	Boolean	Indicates whether the template is blank Only applicable to public templates
categories	string[]	List of categories this template belongs to Only applicable to public templates
description	string	Template description
globalTemplate	string	Type of global template. One of: BLANK_SHEET, PROJECT_SHEET, or TASK_LIST Only applicable to blank public templates
image	string	URL to the small preview image for this template Only applicable to non-blank public templates
largeImage	string	URL to the large preview image for this template Only applicable to non-blank public templates
locale	string	Locale of the template Only applicable to public templates
name	string	Template name
tags	string[]	List of search tags for this template Only applicable to non-blank public templates

List Public Templates

Example request: list public templates

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

smartsheet.templates.listPublicTemplates()
  .then(function(templateList) {
    console.log(templateList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Template> templates = smartsheet.TemplateResources.ListPublicTemplates(
  null            // PaginationParameters
);

// Omit pagination parameters
PagedResult<Template> templates = smartsheet.templateResources().listPublicTemplates(
  null        // PaginationParameters
);

response = smartsheet_client.Templates.list_public_templates(
  page_size=10,
  page=1)
pages = response.total_pages
templates = response.data

response = smartsheet.templates.list_public
templates = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": 3457273486960516,
            "name": "template 1",
            "accessLevel": "OWNER",
            "description": "This is template 1"
        },
        {
            "id": 34572734869609346,
            "name": "template 2",
            "accessLevel": "VIEWER",
            "description": "This is template 2"
        }
    ]
}

GET /templates/public

Gets a list of public templates that the user has access to.

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 Template objects
Access Scope	READ_SHEETS

List User-created Templates

Example request: list user-created templates

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

smartsheet.templates.listUserCreatedTemplates()
  .then(function(templateList) {
    console.log(templateList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Template> templates = smartsheet.TemplateResources.ListUserCreatedTemplates(
  null                // PaginationParameters
);

// Omit pagination parameters
PagedResult<Template> templates = smartsheet.templateResources().listUserCreatedTemplates(
  null        // PaginationParameters
);

response = smartsheet_client.Templates.list_user_created_templates(
  page_size=10,
  page=1)
pages = response.total_pages
templates = response.data

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

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "id": 3457273486960516,
            "name": "template 1",
            "accessLevel": "OWNER",
            "description": "This is template 1"
        },
        {
            "id": 34572734869609346,
            "name": "template 2",
            "accessLevel": "VIEWER",
            "description": "This is template 2"
        }
    ]
}

GET /templates

Gets a list of user-created templates that the user has access to.

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 Template objects
Access Scope	READ_SHEETS

Token

The Smartsheet API utilizes OAuth 2.0 for authentication and authorization. An Authorization HTTP header containing an access token is required to authenticate all API requests except for the requests to GET Access Token or Refresh Access Token. For more information, see Authentication.

Objects

Token Object

Example: Token object

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

access_token	string	A credential that can be used by a client to access the Smartsheet API.
token_type	enum	How an access token will be generated and presented. Smartsheet uses the bearer parameter, which means essentially give access to the bearer of this token.
expires_in	number	Number of seconds token is valid once issued; this is currently 604799 seconds, or approx. 7 days.
refresh_token	string	A credential tied to the access token that can be used to obtain a fresh access token with the same permissions, without further involvement from a user.

Get Access Token

Example request: get 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
)

Example response

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

POST /token

Gets an access token, as part of the OAuth process. For more information, see OAuth Flow.

Headers	Content-Type: application/x-www-form-urlencoded
Parameters	client_id (required) -- client id for your app
	code (required) -- authorization code returned during the OAuth flow.
	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.
Returns	Token object containing an access token and a refresh token.

Refresh Access Token

Example request: refresh 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
)

Example response

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

POST /token

Refreshes an access token, as part of the OAuth process. For more information, see OAuth Flow.

Headers	Content-Type: application/x-www-form-urlencoded
Parameters	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
	refresh_token (required) -- refresh_token value that came with the access token
Returns	Token object containing an access token and a refresh token.

Revoke Access Token

Example request: revoke access token

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

smartsheet.tokens.revokeAccessToken({})
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.TokenResources.RevokeAccessToken();

smartsheet.tokenResources().revokeAccessToken();

smartsheet_client.Token.revoke_access_token()

smartsheet.token.revoke

Example response

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

DELETE /token

Revokes the access token used to make this request. The access token is no longer valid, and subsequent API calls made using the token fail.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	deleteAllForApiClient (optional): The client Id and user Id is fetched based on the token that is used to make this API call. A value of true deletes all tokens associated to the given client Id and user Id. Defaults to false.
Returns	Result object

Update Requests

Objects

UpdateRequest Object

Example: UpdateRequest object

{
  "sendTo": [
    {"email": "recipient1@smartsheet.com"}
  ],
  "subject": "Sample Monthly Update Request",
  "message": "Please update my online sheet.",
  "ccMe": false,
  "includeAttachments": true,
  "includeDiscussions": true,
  "columnIds": [],
  "rowIds": [],
  "id": 7820135625975684,
  "sentBy": {
    "name": "John Doe",
    "email": "john.doe@smartsheet.com"
  },
  "schedule": {
    "type": "MONTHLY",
    "startAt": "2016-04-01T19:00:00Z",
    "endAt": "2016-12-31T07:00:00Z",
    "dayOfMonth": 1,
    "repeatEvery": 1,
    "lastSentAt": "2016-05-01T19:00:03Z",
    "nextSendAt": "2016-06-01T19:00:00Z"
  },
  "createdAt": "2016-03-28T18:45:59Z",
  "modifiedAt": "2016-03-28T18:45:59Z"
}

The UpdateRequest object extends the MultiRowEmail object, adding the following:

id	number	Id of the update request.
createdAt	timestamp	The date and time for when this request was originally created. Read-only.
modifiedAt	timestamp	The date and time for when the last change was made to this request. Read-only.
schedule	Schedule	The schedule for which update requests are sent out.
sentBy	User	User object containing name and email of the sender.

SentUpdateRequest Object

id	number	Id of the sent update request.
columnIds	number[]	Ids of columns included in the request.
rowIds	number[]	Ids of rows update is requested.
updateRequestId	number	Id of the originating update request.
includeAttachments	Boolean	Indicates whether the attachments were included in the email.
includeDiscussions	Boolean	Indicates whether the discussions were included in the email.
message	string	The message of the email. Max 10000 characters.
sentAt	timestamp	The date and time for when the sent update request was sent to the recipient.
sentBy	User	User object containing name and email of the sender.
sentTo	Recipient	Recipient object.
status	string	The status of the sent update request. It must be one of the following values: CANCELED: The request was canceled. COMPLETE: The request has been responded by the recipient. PENDING: The request has not been responded by the recipient.
subject	string	The subject of the email.

Schedule Object

type	string	Schedule type. It must be one of the following values: ONCE, DAILY, WEEKLY, MONTHLY, or YEARLY
dayDescriptors	string[]	A string array consists of one or more of the following values: DAY, WEEKDAY, WEEKEND SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY The subset of values applicable to the schedule type are as followed: Value Daily schedule Weekly schedule Monthly schedule DAY ✓ WEEKDAY ✓ ✓ WEEKEND ✓ SUNDAY ✓ ✓ MONDAY ✓ ✓ TUESDAY ✓ ✓ WEDNESDAY ✓ ✓ THURSDAY ✓ ✓ FRIDAY ✓ ✓ SATURDAY ✓ ✓ For more details, refer to the Table of Schedule Object’s Attributes below.
dayOfMonth	number	The day within the month. Valid range is 1 to 28. This attribute is applicable to the following schedule type: MONTHLY For more details, refer to the Table of Schedule Object’s Attributes below.
dayOrdinal	string	Must be one of the following values: FIRST or LAST SECOND, THIRD, or FOURTH This attribute is applicable to the following schedule type: MONTHLY For more details, refer to the Table of Schedule Object’s Attributes below.
endAt	timestamp	The date, time, and time zone at which the delivery schedule ends. The value is either in a string format or a numeric format: When the value is a string, it must be a valid ISO-8601 date and time with an offset (YYYY-MM-DDThh:mm:ssTZD). When the value is a number, it represents a date and time with no offset (UTC time zone). See Dates and Times for more information. The value must be later than startAt and the current date and time. The value must contain zero hours, zero minutes, and zero seconds. The offset (time zone) value must be the same as the offset (time zone) value in startAt. This attribute is applicable to the following schedule types: DAILY, WEEKLY, MONTHLY, YEARLY. For more details, refer to the Table of Schedule Object’s Attributes below.
lastSentAt	timestamp	The date and time for when the last request was sent. Read-only.
nextSendAt	timestamp	The date and time for when the next request is scheduled to send. Read-only.
repeatEvery	number	Frequency on which the request is delivered. The unit is a function of the type attribute. For example, for MONTHLY schedule, repeatEvery=1 means every month. Valid range is 1 to 99. This attribute is applicable to the following schedule types: DAILY, WEEKLY, MONTHLY, or YEARLY. For more details, refer to the Table of Schedule Object’s Attributes below.
startAt	timestamp	The date, time, and time zone at which the first delivery starts. The value is either in a string format or a numeric format: When the value is a string, it must be a valid ISO-8601 date and time with an offset (YYYY-MM-DDThh:mm:ssTZD). When the value is a number, it represents a date and time with no offset (UTC time zone). See Dates and Times for more information. For ONCE schedule type, it must be later than the current date time. For all other schedule types, it must be later than “2000-01-01T00:00:00Z” in string format or 946684800000 in numeric format. The value must contain zero minutes and zero seconds. This attribute is applicable to all schedule types. For more details, refer to the Table of Schedule Object’s Attributes below.

Table of Schedule Object’s Attributes

The following table shows valid attribute values for each of the schedule types.

Attributes	Send Now	Deliver On	Daily Schedule	Weekly Schedule	Monthly Schedule	Yearly Schedule
type	ONCE	ONCE	DAILY	WEEKLY	MONTHLY	YEARLY
dayDescriptors	N/A	N/A	Required (see Note 1)	Required (see Note 2)	Required (see Note 3)	N/A
dayOfMonth	N/A	N/A	N/A	N/A	Required (see Note 3)	N/A
dayOrdinal	N/A	N/A	N/A	N/A	Required (see Note 3)	N/A
endAt	N/A	N/A	Optional	Optional	Optional	Optional
repeatEvery	N/A	N/A	Required (see Note 1)	Required	Required	Required
startAt	N/A	Required	Required	Required	Required	Required

NOTES:

1. For DAILY schedule, only one of the attributes can be specified:
   • repeatEvery, or
   • dayDescriptors. The only supported value is WEEKDAY.
2. For WEEKLY schedule, the dayDescriptors attribute requires one or more of the following values: SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, or SATURDAY.
3. For MONTHLY schedule, only one of the following attribute combinations are valid:
   • dayOfMonth, or
   • dayOrdinal together with dayDescriptors. dayDescriptors should contain only one value.
4. If you prefer to use date-based rules, "frequency" settings are ignored, for instance, Oct 31 and DAILY defaults to Oct 31.

Create Update Request

Example request: create update request

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ 
  "sendTo": [ 
    {"email": "recipient1@smartsheet.com"}, 
    {"email": "recipient2@smartsheet.com"} 
  ], 
  "subject": "Sample Monthly Update Request", 
  "message": "Please update my online sheet.", 
  "ccMe": false, 
  "rowIds": [4508292249610116, 2256492435924868], 
  "columnIds": [4508284196546436, 2256484382861188], 
  "includeAttachments": false, 
  "includeDiscussions": false 
}' 

// Specify recipients
Recipient[] recipientSpecification = new Recipient[] {
  new Recipient { Email = "recipient1@smartsheet.com"}
};

// Configure update request
UpdateRequest updateRequestSpecification = new UpdateRequest
{
  SendTo = recipientSpecification,
  Subject = "Sample Monthly Update Request",
  Message = "Please update my online sheet.",
  CcMe = true,
  RowIds = new long[] { 1123834706323332, 5627434333693828 },
  ColumnIds = new long[] { 4549065498224516, 2297265684539268 },
  IncludeAttachments = true,
  IncludeDiscussions = true
};

// Send update request via email
UpdateRequest newUpdateRequest = smartsheet.SheetResources.UpdateRequestResources.CreateUpdateRequest(
  3285357287499652,       // long sheetId
  updateRequestSpecification
);

// Set body
var body = {
  rowIds: [
    1049041315358596,
    5552640942729092
  ],
  includeAttachments: true,
  includeDiscussions: false,
  sendTo: [
    {
      email: "jane.roe@smartsheet.com"    
    }
  ],
  subject: "Sample Monthly Update Request",
  message: "Please update my online sheet.",
  schedule: {
    type: "DAILY",
    startAt: "2016-04-01T00:00:00Z",
    endAt: "2018-12-31T00:00:00Z",
    dayDescriptors: [
      "WEEKDAY"
    ]
  }
};

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

// Create update request
smartsheet.sheets.createUpdateRequest(options)
  .then(function(updatedRequest) {
    console.log(updatedRequest);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify recipients
RecipientEmail recipientA = new RecipientEmail()
  .setEmail("recipient1@smartsheet.com");

RecipientEmail recipientB = new RecipientEmail()
  .setEmail("recipient2@smartsheet.com");

List<Recipient> recipients = Arrays.asList(recipientA, recipientB);

// Specify parameters for update request
UpdateRequest updateRequest = new UpdateRequest();
updateRequest.setRowIds((Arrays.asList(3344087179913092L, 7847686807283588L));
updateRequest.setSendTo(recipients)
  .setSubject("Sample Monthly Update Request")
  .setMessage("Please update my online sheet.")
  .setColumnIds(Arrays.asList(1735559124150148L, 1735559124150148L))
  .setIncludeAttachments(false)
  .setIncludeDiscussions(false);

// Create update request
smartsheet.sheetResources().updateRequestResources().createUpdateRequest(
  1639534409607044L,      // long sheetId
  updateRequest
);

# Configure email
email_spec = ss_client.models.MultiRowEmail()
email_spec.send_to = [
  ss_client.models.Recipient({'email': 'recipient1@smartsheet.com'}),
  ss_client.models.Recipient({'email': 'recipient2@smartsheet.com'})]
email_spec.subject = 'Please update based on meeting'
email_spec.message = 'some message'
email_spec.cc_me = False
email_spec.row_ids = [6809535313667972]
email_spec.column_ids = [7036894123976580]

# Send update request
new_update_request = ss_client.Sheets.create_update_request(
  5190835902932868,           # sheet_id
  email_spec
)

body = {
  send_to: [
    {
      email: 'jane.roe@smartsheet.com'
    }
  ],
  row_ids: [
    7886095586224004,
    2661640373069700
  ],
  column_ids: [
    6962516556310404,
    3584816835782532
  ],
  include_attachments: true,
  include_discussions: true,
  layout: 'VERTICAL',
  subject: 'Sample Monthly Update Request',
  message: 'Please update my online sheet.',
  cc_me: false,
  schedule: {
    type: 'MONTHLY',
    start_at: '2016-04-01T19:00:00Z',
    end_at: '2016-12-31T07:00:00Z',
    day_descriptors: [
      'WEEKDAY'
    ]
  }
}

new_update_request = smartsheet.update_requests.create(
  sheet_id: 7820135625975684,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "sendTo": [
            {"email": "jane.roe@smartsheet.com"}
        ],
        "subject": "Sample Monthly Update Request",
        "message": "Please update my online sheet.",
        "ccMe": false,
        "includeAttachments": true,
        "includeDiscussions": true,
        "columnIds": [6962516556310404, 3584816835782532],
        "rowIds": [7886095586224004],
        "id": 7820135625975684,
        "sentBy": {
            "name": "John Doe",
            "email": "john.doe@smartsheet.com"
        },
        "schedule": {
            "type": "MONTHLY",
            "startAt": "2016-04-01T19:00:00Z",
            "endAt": "2016-12-31T07:00:00Z",
            "dayOfMonth": 1,
            "repeatEvery": 1,
            "nextSendAt": "2016-05-01T19:00:00Z"
        }
    }
}

Example request: create immediate update request

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ 
  "sendTo": [ 
    {"email": "recipient1@smartsheet.com"} 
  ], 
  "subject": "Sample Monthly Update Request", 
  "message": "Please update my online sheet.", 
  "ccMe": false, 
  "rowIds": [7886095586224004], 
  "columnIds": [6962516556310404, 3584816835782532], 
  "includeAttachments": true, 
  "includeDiscussions": true, 
  "schedule": { 
  "type": "MONTHLY", 
  "startAt": "2016-04-01T19:00:00Z", 
  "endAt": "2016-12-31T07:00:00Z", 
  "dayOfMonth": 1, 
  "repeatEvery": 1 
    } 
}'

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "sendTo": [
      {"email": "recipient1@smartsheet.com"},
    {"email": "recipient2@smartsheet.com"}
  ],
  "subject": "some subject",
  "message": "some message",
  "ccMe": false,
  "includeAttachments": false,
  "includeDiscussions": false,
  "columnIds": [4508284196546436, 2256484382861188],
  "rowIds": [4508292249610116, 2256492435924868],
  "id": 4523799765903236,
  "sentBy": {
    "name": "John Doe",
    "email": "john.doe@smartsheet.com"
  },
  "schedule": {
    "type": "ONCE",
    "startAt": "2016-05-16T22:33:28Z",
    "nextSendAt": "2016-05-16T22:33:28Z"
    }
  }
}

POST /sheets/{sheetId}/updaterequests

Creates an update request for the specified rows within the sheet. An email notification (containing a link to the update request) is sent to the specified recipients according to the specified schedule.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	UpdateRequest object. The UpdateRequest object in the request body must specify one or more of the following attributes: rowIds: number[] sendTo: Recipient[] One or more of the followings: columnIds: number[] includeAttachments: true includeDiscussions: true The following attributes have the following values when not specified: ccMe: false message: Please update the following rows in my online sheet. subject: Update Request: {Sheet Name} When the Schedule object is not specified, the request is sent to the recipients immediately.
Returns	Result object containing the newly created UpdateRequest object.
Errors	If an error occurs because the request specified one or more alternate email addresses, please retry using the primary email address.
Access Scope	WRITE_SHEETS

Delete Update Request

Example request: delete update request

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

smartsheet.SheetResources.UpdateRequestResources.DeleteUpdateRequest(
  3285357287499652,      // long sheetId
  2409350321989508       // long updateRequestId
);

// Set options
var options = {
  sheetId: 3285357287499652,
  updateRequestId: 2409350321989508
};

// Delete update request
smartsheet.sheets.deleteUpdateRequest(options)
  .then(function(result) {
    console.log(result);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.sheetResources().updateRequestResources().deleteUpdateRequest(
  1639534409607044L,      // long sheetId
  965780272637828L        // long updateRequestId
);

ss_client.Sheets.delete_update_request(
  5190835902932868,        # sheet_id
  7444581001258884         # update_request_id
)

smartsheet.update_requests.delete(
  sheet_id: 3294745817573252,
  update_request_id: 4523799765903236
)

Example response

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

DELETE /sheets/{sheetId}/updaterequests/{updateRequestId}

Terminates the future scheduled delivery of the update request specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	Must be one of the followings:ADMIN_SHEETS or WRITE_SHEETS

Get Update Request

Example request: get update request

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

UpdateRequest results = smartsheet.SheetResources.UpdateRequestResources.GetUpdateRequest(
  3285357287499652,      // long sheetId
  2409350321989508       // long updateRequestId
);

// Set options
var options = {
  sheetId: 3285357287499652,
  updateRequestId: 2409350321989508
};

// Get update request
smartsheet.sheets.getUpdateRequest(options)
  .then(function(updateRequest) {
    console.log(updateRequest);
  })
  .catch(function(error) {
    console.log(error);
  });

UpdateRequest results = smartsheet.sheetResources().updateRequestResources().getUpdateRequest(
  1639534409607044L,      // long sheetId
  965780272637828L        // long updateRequestId
);

response = ss_client.Sheets.get_update_request(
  5190835902932868,       # sheet_id
  7510551698925444        # update_request_id
)

update_request = smartsheet.update_requests.get(
  sheet_id: 3294745817573252,
  update_request_id: 4523799765903236
)

Example response

{
    "sendTo": [
        {"email": "recipient1@smartsheet.com",
         "profileImage": []}
    ],
    "subject": "Sample Monthly Update Request",
    "message": "Please update my online sheet.",
    "ccMe": false,
    "includeAttachments": true,
    "includeDiscussions": true,
    "columnIds": [ 6962516556310404, 3584816835782532 ],
    "rowIds": [ 7886095586224004 ],
    "id": 7820135625975684,
    "sentBy": {
        "name": "John Doe",
        "email": "john.doe@smartsheet.com"
    },
    "schedule": {
        "type": "MONTHLY",
        "startAt": "2016-04-01T19:00:00Z",
        "endAt": "2016-12-31T07:00:00Z",
        "dayOfMonth": 1,
        "repeatEvery": 1,
        "lastSentAt": "2016-05-01T19:00:03Z",
        "nextSendAt": "2016-06-01T19:00:00Z"
    },
    "createdAt": "2016-03-28T18:45:59Z",
    "modifiedAt": "2016-03-28T18:45:59Z"
}

GET /sheets/{sheetId}/updaterequests/{updateRequestId}

Gets the specified update request for the sheet that has a future schedule.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	UpdateRequest object. The rowIds and columnIds in the returned UpdateRequest object represent the list at the time the update request was created or last modified. The lists may contain Ids of rows or columns that are no longer valid (for example, they have been removed from the sheet).
Access Scope	READ_SHEETS

Get All Update Requests

Example request: list update requests

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

PaginatedResult<UpdateRequest> results = smartsheet.SheetResources.UpdateRequestResources.ListUpdateRequests(
  1639534409607044L,      // long sheetId
  null                    // PaginationParameters
);

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

// List update requests
smartsheet.sheets.getAllUpdateRequests(options)
  .then(function(requestsList) {
    console.log(requestsList);
  })
  .catch(function(error) {
    console.log(error);
  });

PagedResult<UpdateRequest> results = smartsheet.sheetResources().updateRequestResources().listUpdateRequests(
  1639534409607044L,      // long sheetId
  null                    // PaginationParameters
);

response = ss_client.Sheets.list_update_requests(5190835902932868)      # sheet_id
update_requests = response.data

response = smartsheet.update_requests.list(
  sheet_id: 3294745817573252
)
update_requests = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
  "data": [
    {
      "sendTo": [
        {"email": "recipient1@smartsheet.com"}
      ],
      "subject": "Sample Monthly Update Request",
      "message": "Please update my online sheet.",
      "ccMe": false,
      "id": 7820135625975684,
      "sentBy": [{
        "name": "John Doe",
        "email": "john.doe@smartsheet.com"
      }],
      "schedule": [{
        "type": "MONTHLY",
        "startAt": "2016-04-01T19:00:00Z",
        "endAt": "2016-12-31T07:00:00Z",
        "dayOfMonth": 1,
        "repeatEvery": 1,
        "lastSentAt": "2016-05-01T19:00:03Z",
        "nextSendAt": "2016-06-01T19:00:00Z"
      }],
      "createdAt": "2016-03-28T18:45:59Z",
      "modifiedAt": "2016-03-28T18:45:59Z"
  },
  {
      "sendTo": [
        {"email": "recipient2@smartsheet.com"},
        {"email": "recipient3@smartsheet.com"}
      ],
      "subject": "Bi-montrhly Update Request",
      "message": "Please update my online sheet.",
      "ccMe": true,
      "id": 6553498230777732,
      "sentBy": [{
      "name": "John Doe",
        "email": "john.doe@smartsheet.com"
      }],
      "schedule": [{
        "type": "MONTHLY",
        "startAt": "2016-04-01T17:00:00Z",
        "endAt": "2016-12-31T08:00:00Z",
        "dayOrdinal": "LAST",
        "dayDescriptors": [ "WEEKEND" ],
        "repeatEvery": 2,
        "lastSentAt": "2016-04-30T17:00:04Z",
        "nextSendAt": "2016-06-26T17:00:00Z"
      }],
      "createdAt": "2016-03-04T00:06:29Z",
      "modifiedAt": "2016-03-04T00:06:29Z"
    }
  ]
}

GET /sheets/{sheetId}/updaterequests

Gets a summarized list of all update requests that have future schedules associated with the specified sheet.

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 UpdateRequest objects limited to the following attributes: id ccMe createdAt message modifiedAt schedule sendTo sentBy subject
Access Scope	READ_SHEETS

Change Update Request

Example request: change update request

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests/{updateRequestId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{ 
  "subject": "Sample Monthly Update Request", 
  "message": "Please update my online sheet."
}'

// Identify the update request you want to change
UpdateRequest updateRequestSpecification = new UpdateRequest
{
  Id = 7178482007467908,        // long updateRequestId
  Subject = "Sample Monthly Update Request",
  Message = "Please update my online sheet."
};

// Change update request
UpdateRequest updatedUpdateRequest = smartsheet.SheetResources.UpdateRequestResources.UpdateUpdateRequest(
  3285357287499652,          // long sheetId
  updateRequestSpecification
);

// Set text
var body = {
  subject: "Sample Monthly Update Request"
};

// Set options
var options = {
  sheetId: 3285357287499652,
  updateRequestId: 7178482007467908,
  body: body
};

// Change update request
smartsheet.sheets.changeUpdateRequest(options)
  .then(function(updatedRequest) {
    console.log(updatedRequest);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

# [todo]

body = {
  send_to: [
    {
      email: 'jane.roe@smartsheet.com'
    }
  ],
  column_ids: [
    6962516556310404,
    3584816835782532
  ],
  include_attachments: false,
  include_discussions: false,
  subject: 'Sample Monthly Update Request',
  message: "Please update my online sheet.",
  cc_me: false,
  schedule: {
    type: 'MONTHLY',
    start_at: '2016-04-01T19:00:00Z',
    end_at: '2016-12-31T07:00:00Z',
    day_ordinal: 'SECOND',
    day_descriptors: [
      'THURSDAY'
    ],
    repeat_every: 2
  }
}

update_request = smartsheet.update_requests.update(
  sheet_id: 3294745817573252,
  update_request_id: 7820135625975684,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "sendTo": [
            {"email": "jane.roe@smartsheet.com"}
        ],
        "subject": "Sample Monthly Update Request",
        "message": "Please update my online sheet.",
        "ccMe": false,
        "includeAttachments": true,
        "includeDiscussions": true,
        "columnIds": [6962516556310404, 3584816835782532],
        "rowIds": [7886095586224004],
        "id": 7820135625975684,
        "sentBy": {
            "name": "John Doe",
            "email": "john.doe@smartsheet.com"
        },
        "schedule": {
            "type": "MONTHLY",
            "startAt": "2016-04-01T19:00:00Z",
            "endAt": "2016-12-31T07:00:00Z",
            "dayOfMonth": 1,
            "repeatEvery": 1,
            "nextSendAt": "2016-05-01T19:00:00Z"
        }
    }
}

PUT /sheets/{sheetId}/updaterequests/{updateRequestId}

Changes the specified update request for the sheet.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	UpdateRequest object. The UpdateRequest object in the request body must specify one or more of the following attributes: ccMe: Boolean columnIds: number[] includeAttachments: Boolean includeDiscussions: Boolean message: string schedule: Schedule object sendTo: Recipient[] subject: string
Returns	Result object containing the modified UpdateRequest object.
Errors	If an error occurs because the request specified one or more alternate email addresses, please retry using the primary email address.
Access Scope	WRITE_SHEETS

Delete Sent Update Request

Example request: delete sent update request

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

smartsheet.SheetResources.UpdateRequestResources.DeleteSentUpdateRequest(
  3285357287499652,      // long sheetId
  2303451729291140       // long sentUpdateRequestId
);

// Set options
var options = {
  sheetId: 1639534409607044,
  sentUpdateRequestId: 965780272637828
};

// Delete sent update request
smartsheet.sheets.deleteSentUpdateRequest(options)
  .then(function(result) {
    console.log(result);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.sheetResources().updateRequestResources().deleteSentUpdateRequest(
  1639534409607044L,      // long sheetId
  965780272637828L        // long sentUpdateRequestId
);

ss_client.Sheets.delete_sent_update_request(
  5190835902932868,   # sheet_id
  381297098024836     # sent_update_request_id
)

smartsheet.update_requests.sent.delete(
  sheet_id: 3294745817573252,
  sent_update_request_id: 965780272637828
)

Example response

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

DELETE /sheets/{sheetId}/sentupdaterequests/{sentUpdateRequestId}

Deletes the specified sent update request.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	Must be one of the followings: ADMIN_SHEETS or WRITE_SHEETS

Get Sent Update Request

Example request: get sent update request

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

SentUpdateRequest results = smartsheet.SheetResources.UpdateRequestResources.GetSentUpdateRequest(
  3285357287499652,      // long sheetId
  2303451729291140       // long sentUpdateRequestId
);

// Set options
var options = {
  sheetId: 1639534409607044,
  sentUpdateRequestId: 67287475611524
};

// Get sent update request
smartsheet.sheets.getSentUpdateRequest(options)
  .then(function(updateRequest) {
    console.log(updateRequest);
  })
  .catch(function(error) {
    console.log(error);
  });

SentUpdateRequest results = smartsheet.sheetResources().updateRequestResources().getSentUpdateRequest(
  1639534409607044L,      // long sheetId
  67287475611524L         // long sentUpdateRequestId
);

response = ss_client.Sheets.get_sent_update_request(
  5190835902932868,       # sheet_id
  7510551698925444        # update_request_id
)

response = smartsheet.update_requests.sent.get(
  sheet_id: 3294745817573252,
  sent_update_request_id: 965780272637828
)

Example response

{
    "id": 8286878311966596,
    "updateRequestId": 4523799765903236,
    "sentAt": "2016-05-16T22:33:32Z",
    "sentBy": {
        "name": "John Doe",
        "email": "john.doe@smartsheet.com"
    },
    "sentTo": {
        "email": "recipient1@smartsheet.com",
        "profileImage": {
            "imageId": "u!1!8ljfd6w9-aY!fooH0wbarY!y9VvAgUOFdg",
            "height": 1050,
            "width": 1050
            }
        }
    },
    "status": "PENDING",
    "subject": "some subject",
    "message": "some message",
    "rowIds": [ 4508292249610116, 2256492435924868 ],
    "includeAttachments": false,
    "includeDiscussions": false,
    "columnIds": [ 4508284196546436, 2256484382861188 ]
}

GET /sheets/{sheetId}/sentupdaterequests/{sentUpdateRequestId}

Gets the specified sent update request on the sheet.

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

Get All Sent Update Requests

Example request: list sent update requests

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

 PaginatedResult<SentUpdateRequest> results = smartsheet.SheetResources.UpdateRequestResources.ListSentUpdateRequests(
  1639534409607044L,      // long sheetId
  null                    // PaginationParameters
);

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

// List sent update requests
smartsheet.sheets.getAllSentUpdateRequests(options)
  .then(function(requestsList) {
    console.log(requestsList);
  })
  .catch(function(error) {
    console.log(error);
  });

PagedResult<SentUpdateRequest> results = smartsheet.sheetResources().updateRequestResources().listSentUpdateRequests(
  1639534409607044L,      // long sheetId
  null                    // PaginationParameters
);

response = ss_client.Sheets.list_sent_update_requests(
  5190835902932868)      # sheet_id
update_requests = response.data

response = smartsheet.update_requests.sent.list(
  sheet_id: 3294745817573252
)
update_requests = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
  "data": [
    {
      "id": 3319834533488516,               // Sent update request
      "updateRequestId": 6742614230755204,  // Originating update request
      "sentAt": "2016-04-30T01:00:01Z",
      "sentBy": [{
      "name": "John Doe",
        "email": "john.doe@smartsheet.com"
      }],
      "sentTo": [{
        "email": "recipient1@smartsheet.com"
      }],
      "status": "PENDING",
      "subject": "Sample Monthly Update Request",
      "message": "Please update my online sheet."
  },
  {
      "id": 6197256463378308,
      "updateRequestId": 2999876649805700,
      "sentAt": "2016-04-02T22:00:02Z",
      "sentBy": [{
        "name": "John Doe",
        "email": "john.doe@smartsheet.com"
      }],
      "sentTo": [{
        "email": "recipient2@smartsheet.com"
      }],
      "status": "COMPLETED",
      "subject": "Sample Bi-Weekly Update Request",
      "message": "Some message"
  }
  ]
}

GET /sheets/{sheetId}/sentupdaterequests

Gets a summarized list of all sent update requests on the sheet.

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 SentUpdateRequest objects limited to the following attributes: id message sendTo sentAt sentBy status subject updateRequestId
Access Scope	READ_SHEETS

Users

Objects

User Object

Example: User object

{
  "email": "john.doe@smartsheet.com",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "profileImage": {},
  "id": 48569348493401200,
  "status": "ACTIVE",
  "admin": true,
  "licensedSheetCreator": true,
  "groupAdmin": true,
  "resourceViewer": true, 
  "sheetCount": 3,
  "lastLogin": "2016-08-15T18:32:47Z",
  "customWelcomeScreenViewed": "2016-08-12T12:15:47Z"
}

id	number	User Id
admin	Boolean	Indicates whether the user is a system admin (can manage user accounts and organization account)
customWelcomeScreenViewed	timestamp	Timestamp of viewing an Enterprise Custom Welcome Screen by the current user
email	string	User's primary email address
firstName	string	User's first name
groupAdmin	Boolean	Indicates whether the user is a group admin (can create and edit groups)
lastLogin	timestamp	Last login time of the current user
lastName	string	User's last name
licensedSheetCreator	Boolean	Indicates whether the user is a licensed user (can create and own sheets)
name	string	User's full name (read-only)
profileImage	Image	An Image object representing the profile image associated with the user account
resourceViewer	Boolean	Indicates whether the user is a resource viewer (can access resource views)
sheetCount	number	The number of sheets owned by the current user within the organization account
status	string	User status, set to one of the following values: ACTIVE, DECLINED, or PENDING

UserProfile Object

id	number	Current user's Id
account	Account	Account object representing the current user's customer account
admin	Boolean	Indicates whether the user is a system admin (can manage user accounts and organization account)
alternateEmails	AlternateEmail[]	An array of AlternateEmail objects representing the alternate email addresses associated with the user account
company	string	User's company
customWelcomeScreenViewed	timestamp	Timestamp of viewing an Enterprise Custom Welcome Screen by the current user
department	string	User's department
email	string	Current user's primary email address
firstName	string	Current user's first name
groupAdmin	Boolean	Indicates whether the user is a group admin (can create and edit groups)
jiraAdmin	Boolean	Indicates whether the user is a JIRA admin
lastLogin	timestamp	Last login time of the current user
lastName	string	Current user's last name
licensedSheetCreator	Boolean	Indicates whether the user is a licensed user (can create and own sheets)
locale	string	Current user's locale (see Server Information)
mobilePhone	string	User's mobile phone number
profileImage	Image	An Image object representing the profile image associated with the user account
resourceViewer	Boolean	Indicates whether the user is a resource viewer (can access resource views)
role	string	User's role
salesforceAdmin	Boolean	Indicates whether the user is a Salesforce admin
salesforceUser	Boolean	Indicates whether the user is a registered Salesforce user
sheetCount	number	The number of sheets owned by the current user within the organization account
timeZone	string	Current user's time zone Id
title	string	User's title
workPhone	string	User's work phone number

Account Object

id	number	Account Id
name	string	Account name

AlternateEmail Object

id	number	AlternateEmail Id
confirmed	Boolean	Indicates whether the alternate email address has been confirmed
email	string	User's alternate email address

Add User

Example request: add user

curl 'https://api.smartsheet.com/2.0/users?sendEmail=true' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"firstName": "John", "lastName": "Doe", "email": "john.doe@smartsheet.com", "admin": false, "licensedSheetCreator": true}'

// Specify user properties
var user = {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@smartsheet.com",
    "admin": false,
    "licensedSheetCreator": true
};

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

// Add user
smartsheet.users.addUser(options)
    .then(function(newUser) {
        console.log(newUser)
    }).catch(function(error) {
        console.log(error);
    });

// Set user properties
User userSpecification = new User
{
  Email = "john.doe@smartsheet.com",
  Admin = false,
  LicensedSheetCreator = true,
  FirstName = "John",
  LastName = "Doe"
};

// Add user
User newUser = smartsheet.UserResources.AddUser(
  userSpecification,
  true,                   // Nullable<bool> sendEmail
  null                    // Nullable<bool> allowInviteAccountAdmin
);

// Set user properties
User userSpecification = new User();
userSpecification.setAdmin(false)
  .setEmail("john.doe@smartsheet.com")
  .setFirstName("John")
  .setLastName("Doe")
  .setLicensedSheetCreator(true);

// Add user
User newUser = smartsheet.userResources().addUser(userSpecification);

new_user = smartsheet_client.Users.add_user(
  smartsheet.models.User({
    'first_name': 'John',
    'last_name': 'Doe',
    'email': 'john.doe@smartsheet.com',
    'admin': False,
    'licensed_sheet_creator': True
  })
)

# Set user properties
body = {
  email: 'john.doe@smartsheet.com',
  admin: false,
  licensed_sheet_creator: false,
  first_name: 'John',
  last_name: 'Doe',
  resource_viewer: false
}

# Add user
response = smartsheet.users.add(
  body: body
)
new_user = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "id": 94094820842,
    "email": "john.doe@smartsheet.com",
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "profileImage": {
      "imageId": "u!1!8ljad7w9-aY!AsDeH0wWv1Y!y9VvAgUOFdg",
      "height": 1050,
      "width": 1050
    },
    "status": "ACTIVE",
    "admin": true,
    "licensedSheetCreator": true,
    "groupAdmin": true,
    "resourceViewer": true
  }
}

POST /users

Adds a user to the organization account.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	sendEmail (optional): A Boolean that indicates whether to send a welcome email. Defaults to false.
Request Body	User object with the following attributes: admin (required) email (required) licensedSheetCreator (required) firstName (optional) lastName (optional) groupAdmin (optional) resourceViewer (optional)
Returns	Result object containing the newly created User object.
Errors	If an error occurs because the request specified the alternate email address (that is, not the primary email address) of an existing Smartsheet user (to invite the user into the org), the Error object returned contains a detail attribute set to an array of objects, each object in the array having the following attributes: alternateEmailAddress: User's alternate email address that was specified in the request primaryEmailAddress: User's primary email address that must instead be specified for the operation For example: {   "errorCode": 5xxx,   "message": "The specified email address (u1+1@smartsheet.com) is an alternate address for a user with the primary email address of u1@smartsheet.com. Please retry using their primary address."   "detail": [       {         "alternateEmailAddress": "u1+1@smartsheet.com",         "primaryEmailAddress": "u1@smartsheet.com"       }   ] }
Access Scope	ADMIN_USERS

Alternate Email Addresses

A User in Smartsheet must have a primary email address associated with their user account (User.email) and may optionally have one or more alternate email addresses associated with their account (User.alternateEmails).

Add Alternate Emails

Example request: add alternate emails

curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"email": "John.Doe@smartsheet.com"}]'

// Specify email addresses to add
var body = [
  {
    email: "John.Doe@smartsheet.com"
  }
];

// Set options
var options = {
  userId: 4495214342629252,
  body: body
};

// Add alternate email address
smartsheet.users.addAlternateEmail(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

// [todo]

// [todo]

response = smartsheet_client.Users.add_alternate_email(
  4495214342629252,          # user_id
  [
    smartsheet.models.AlternateEmail({
        'email': 'John.Doe@smartsheet.com'
    })
  ]
)

# Set options
body = [
  {
    email: 'John.Doe@smartsheet.com'
  }
]

# Add alternate email addresses
response = smartsheet.users.alternate_emails.add(
  user_id: 4495214342629252,
  body: body
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": [{
        "id": 4495214342629252,
        "email": "John.Doe@smartsheet.com",
        "confirmed": false
    }]
}

POST /users/{userId}/alternateemails

Adds one or more alternate email addresses for the specified user.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Array of AlternateEmail objects, each limited to only the email attribute
Returns	Result object containing an array of the newly created AlternateEmail objects.
Errors	If a single email address is specified in the request and an error occurs, the response contains an Error object. If multiple email addresses are specified in the request and an error occurs, the Error object returned contains a detail attribute set to an array of objects, each object in the array having the following attributes: email: Problematic email address specified in the request errorCode: Smartsheet error code message: Message that describes the problem with the specified email address For example: {   "errorCode": 1160,   "message": "Invalid bulk request. See detail for more information."   "detail": [       {         "email": "altEmail1@smartsheet.com",         "errorCode": 1157,         "message": "This address is already associated with another Smartsheet account, so it cannot be added as an alternate address for this account."       }   ] }
Access Scope	ADMIN_USERS

Make Alternate Email Primary

Example request: make alternate email primary

curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternatEmailId}/makeprimary \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST

// Set options
var options = {
  userId: 401090454808452,
  alternateEmailId: 123456789012345
};

// Make alternate email primary
smartsheet.users.makeAlternateEmailPrimary(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

AlternateEmail primaryEmail = smartsheet.UserResources.PromoteAlternateEmail(
  401090454808452,        // long userId
  123456789012345         // long altEmailId
);

// [todo]

response = smartsheet_client.Users.promote_alternate_email(
  401090454808452,        # user_id
  123456789012345)        # alt_id

response = smartsheet.users.alternate_emails.make_primary(
  user_id: 401090454808452,
  alternate_email_id: 123456789012345
)

Example response

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "id": 123456789012345,
        "email": "John.Doe@smartsheet.com",
        "confirmed": true
    }
}

POST /users/{userId}/alternateemails/{alternateEmailId}/makeprimary

Makes the specified alternate email address to become the primary email address for the specified user.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Returns	Result object containing the AlternateEmail object that is now the primary email address
Errors	If an error occurs because the special permission is not granted to change primary email address, contact Smartsheet (api@smartsheet.com) for assistance to enable this feature. If an error occurs because the specified user has a personal email address as the primary email address (that is. the email address domain cannot be validated, the specified user needs to manually change the primary email address in the Personal Settings.
Access Scope	ADMIN_USERS

Delete Alternate Email

Example request: delete alternate email

curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternatEmailId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  userId: 401090454808452,
  alternateEmailId: 123456789012345
};

// Delete alternate email address
smartsheet.users.deleteAlternateEmail(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.UserResources.DeleteAlternateEmail(
  401090454808452,        // long userId
  123456789012345         // long altEmailId
);

smartsheet.userResources().deleteAlternateEmail(
  401090454808452L,        // long userId
  123456789012345L         // long altEmailId
);

smartsheet_client.Users.delete_alternate_email(
  401090454808452,        # user_id
  123456789012345)        # alternate_email_id

smartsheet.users.alternate_emails.delete(
  user_id: 401090454808452,
  alternate_email_id: 123456789012345
)

Example response

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

DELETE /users/{userId}/alternateemails/{alternateEmailId}

Deletes the specified alternate email address for the specified user.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_USERS

Get Alternate Email

Example request: get alternate email

curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternateEmailId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  userId: 401090454808452,
  alternateEmailId: 123456789012345
};

// Get alternate email address
smartsheet.users.getAlternateEmail(options)
  .then(function(email) {
    console.log(email);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.UserResources.GetAlternateEmail(
  401090454808452,        // long userId
  123456789012345         // long altEmailId
);

smartsheet.userResources().getAlternateEmail(
  401090454808452L,        // long userId
  123456789012345L         // long altEmailId
);

alt_email = smartsheet_client.Users.get_alternate_email(
  401090454808452,        # user_id
  123456789012345)        # alternate_email_id

alt_email = smartsheet.users.alternate_emails.get(
  user_id: 401090454808452,
  alternate_email_id: 123456789012345
)

Example response

{
    "id": 123456789012345,
    "email": "John.Doe@smartsheet.com",
    "confirmed": true
}

GET /users/{userId}/alternateemails/{alternateEmailId}

Gets the specified alternate email.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	AlternateEmail object
Access Scope	READ_USERS

List Alternate Emails

Example request: list alternate emails

curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

// Set options
var options = {
  userId: 123456789012345
};

// List alternate email addresses
smartsheet.users.listAlternateEmails(options)
  .then(function(emailList) {
    console.log(emailList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit 'email' parameter and pagination parameters
PaginatedResult<AlternateEmail> results = smartsheet.UserResources.ListAlternateEmails(
  123456789012345,        // long userId
  null                    // PaginationParameters
);

// Omit 'email' parameter and pagination parameters
PagedResult<AlternateEmail> results = smartsheet.userResources().listAlternateEmails(
  123456789012345L,        // long userId
  null                    // PaginationParameters
);

response = smartsheet_client.Users.list_alternate_emails(
  123456789012345)        # user_id
emails = response.data

response = smartsheet.users.alternate_emails.list(
  user_id: 123456789012345
)
emails = response[:data]

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 1,
  "data": 
  [{
    "id": 123456789012345,
    "email": "John.Doe@smartsheet.com",
    "confirmed": true
  }]
}

GET /users/{userId}/alternateemails

Gets a list of the alternate emails for the specified user.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	IndexResult object containing an array of AlternateEmail objects
Access Scope	READ_USERS

Get Current User

Example request: get current user

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

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

UserProfile userProfile = smartsheet.UserResources.GetCurrentUser();

UserProfile userProfile = smartsheet.userResources().getCurrentUser();

user_profile = smartsheet_client.Users.get_current_user()

user_profile = smartsheet.users.get_current

Example response

{
  "id": 48569348493401200,
  "email": "john.doe@smartsheet.com",
  "firstName": "John",
  "lastName": "Doe",
  "locale": "en_US",
  "timeZone": "US/Pacific",
  "account": {
    "name": "Team Smartsheet",
    "id": 942513719853956
  },
  "admin": true,
  "licensedSheetCreator": true,
  "groupAdmin": true,
  "resourceViewer": true,
  "jiraAdmin": false,
  "salesforceAdmin": false,
  "salesforceUser": false,
  "alternateEmails": [
    {
      "id": 12345,
      "email": "altEmail1@smartsheet.com",
      "confirmed": true                
    }
  ],
  "title": "Senior Sales Representative",
  "department": "Marketing",
  "company": "Smartsheet",
  "workPhone": "",
  "mobilePhone": "206 123-4567",
  "role": "Sales",
  "profileImage": {
    "imageId": "u!1!8ljad7w9-aY!AsDeH0wWv1Y!y9VvAgUOFdg",
    "height": 1050,
    "width": 1050
  },
  "sheetCount": 3,
  "lastLogin": "2016-08-15T18:32:47Z",
  "customWelcomeScreenViewed": "2016-08-12T12:15:47Z"
}

GET /users/me

Gets the current user.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	include (optional): When specified with a value of groups, response includes an array of groups (groupId, name, and description only) that the user is a member of. NOTE: use assume user if querying about a user other than the current user.
Returns	UserProfile object NOTE: For system administrators, the following UserProfile attributes are included in the response: customWelcomeScreenViewed (only returned when an Enterprise user has viewed the Custom Welcome Screen) lastLogin (only returned if the user has logged in) sheetCount (only returned if the status attribute is ACTIVE)
Access Scope	all scopes

Get User

Example request: get user

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

// Set options
var options = {
    id: 48569348493401200   // Id of user
};

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

UserProfile userProfile = smartsheet.UserResources.GetUser(
  48569348493401200           // long userId
);

UserProfile userProfile = smartsheet.userResources().getUser(
  48569348493401200L           // long userId
);

user_profile = smartsheet_client.Users.get_user(
  48569348493401200)          # user_id

user_profile = smartsheet.users.get(
  user_id: 48569348493401200
)

Example response

{
  "id": 48569348493401200,
  "email": "john.doe@smartsheet.com",
  "firstName": "John",
  "lastName": "Doe",
  "locale": "en_US",
  "timeZone": "US/Pacific",
  "account": {
    "name": "Team Smartsheet",
    "id": 942513719853956
  },
  "admin": true,
  "licensedSheetCreator": true,
  "groupAdmin": true,
  "resourceViewer": true,
  "jiraAdmin": false,
  "salesforceAdmin": false,
  "salesforceUser": false,
  "alternateEmails": [
    {
      "id": 12345,
      "email": "altEmail1@smartsheet.com",
      "confirmed": true                
    }
  ],
  "title": "Senior Sales Representative",
  "department": "Marketing",
  "company": "Smartsheet",
  "workPhone": "",
  "mobilePhone": "206 123-4567",
  "role": "Sales",
  "profileImage": {
    "imageId": "u!1!8ljad7w9-aY!AsDeH0wWv1Y!y9VvAgUOFdg",
    "height": 1050,
    "width": 1050
  },
  "sheetCount": 3,
  "lastLogin": "2016-08-15T18:32:47Z",
  "customWelcomeScreenViewed": "2016-08-12T12:15:47Z"
}

GET /users/{userId}

Gets the user specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	UserProfile object NOTE: For system administrators, the following UserProfile attributes are included in the response): admin customWelcomeScreenViewed (only returned when an Enterprise user has viewed the Custom Welcome Screen) groupAdmin lastLogin (only returned if the user has logged in) licensedSheetCreator resourceViewer sheetCount (only returned if the status attribute is ACTIVE) status
Access Scope	READ_USERS

List Users

Example request: list users

curl 'https://api.smartsheet.com/2.0/users?email=john.doe@smartsheet.com&include=lastLogin' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

smartsheet.users.listAllUsers()
    .then(function(userList) {
        console.log(userList)
    })
    .catch(function(error) {
        console.log(error);
    });

// Sample 1: Omit 'email' parameter and pagination parameters
PaginatedResult<User> users = smartsheet.UserResources.ListUsers(
  null,               // IEnumerable<string> emails
  null                // PaginationParameters
);

// Sample 2: Specify 'email' parameter with value of "john.doe@smartsheet.com" and 'includeAll' parameter with value of 'true'
PaginatedResult<User> users = smartsheet.UserResources.ListUsers(
  new string[] { "john.doe@smartsheet.com" },
  new PaginationParameters(
    true, // includeAll
    null, // int pageSize
    null) // int page
);

// Sample 1: Omit 'email' parameter and pagination parameters
PagedResult<User> users = smartsheet.userResources().listUsers(
  null,       // Set<String> email
  null        // PaginationParameters
);

// Sample 2: Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters()
  .setIncludeAll(true);

// Specify 'email' parameter with value of "john.doe@smartsheet.com" and 'includeAll' parameter with value of 'true'
PagedResult<User> users = smartsheet.userResources().listUsers( new HashSet(Arrays.asList("john.doe@smartsheet.com")), parameters);

# Sample 1; List all
response = smartsheet_client.Users.list_users(include_all=True)
users = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Users.list_users(
  page_size=100,
  page=1)
pages = response.total_pages
users = response.data

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

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 1,
  "data": [
    {
      "id": 94094820842,
      "email": "john.doe@smartsheet.com",
      "name": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "profileImage": {
        "imageId": "u!1!8ljad7w9-aY!AsDeH0wWv1Y!y9VvAgUOFdg",
        "height": 1050,
        "width": 1050
      },
      "status": "ACTIVE",
      "admin": true,
      "licensedSheetCreator": true,
      "groupAdmin": true,
      "resourceViewer": true,
      "sheetCount": 3,
      "lastLogin": "2016-08-15T18:32:47Z",
      "customWelcomeScreenViewed": "2016-08-12T12:15:47Z"
    }
  ]
}

GET /users

Gets a list of users in the organization account. To filter by email, use the optional email query string parameter to specify a list of users' email addresses.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	email (optional): Comma-separated list of email addresses on which to filter the results.
	include (optional): When specified with a value of lastLogin, response includes the lastLogin attribute for each User object if: the request is submitted by a system administrator, and the returned IndexResult object that contains a maximum of 100 User objects.
	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 User objects NOTE: If the API request is submitted by a system administrator, the following User object attributes are included in the response (else, they are omitted from the response): admin groupAdmin licensedSheetCreator resourceViewer sheetCount (omitted if the status attribute is not ACTIVE) status NOTE: If the API request is submitted by a system administrator of an Enterprise account, and Custom Welcome Screen is enabled, the following User object attributes are included in the response (else, they are omitted from the response): customWelcomeScreenViewed (omitted if the user has never viewed the Custom Welcome Screen)
Access Scope	READ_USERS

Remove User

Example request: remove user

curl 'https://api.smartsheet.com/2.0/users/{userId}?transferTo=USER_Id&removeFromSharing=true' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
    id: 94094820842 // Id of User
};

// Remove user
smartsheet.users.removeUser(options)
    .then(function(results) {
        console.log(results)
    })  
    .catch(function(error) {
        console.log(error);
    });

// Transfer ownership of groups and sheets to another user and remove the user from sharing
smartsheet.UserResources.RemoveUser(
  94094820842,                // long userId
  transferToUserId,           // Nullable<long> transferTo
  true,                       // Nullable<bool> transferSheets
  true                        // Nullable<bool> removeFromSharing
);

// Transfer ownership of groups and sheets to another user and remove the user from sharing
DeleteUserParameters parameters = new DeleteUserParameters(
  62123820842L,       // long transferToUserId
  true,               // Boolean transferSheets
  true                // Boolean removeFromSharing
);
smartsheet.userResources().deleteUser(
  94094820842L,        // long userId
  parameters
);

smartsheet_client.Users.remove_user(
  94094820842,                # user_id
  transfer_to=62123820842,    # ownership of groups and sheets transfer to user_id
  remove_from_sharing=True)

smartsheet.users.remove(
  user_id: 94094820842
)

Example response

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

DELETE /users/{userId}

Removes a user from an organization account. User is transitioned to a free collaborator with read-only access to owned reports, sheets, Sights, workspaces, and any shared templates (unless those are optionally transferred to another user).

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	removeFromSharing (optional): Set to true to remove the user from sharing for all sheets/workspaces in the organization account. If not specified, user is not removed from sharing.
	transferSheets (optional): If true, and transferTo is specified, the removed user's sheets are transferred. Else, sheets are not transferred. Defaults to false.
	transferTo (required if user owns groups): The Id of the user to transfer ownership to. If the user being removed owns groups, they are transferred to this user. If the user owns sheets, and transferSheets is true, the removed user's sheets are transferred to this user.
Returns	Result object
Access Scope	ADMIN_USERS

Update User

Example request: update user

curl https://api.smartsheet.com/2.0/users/{userId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"admin": true, "licensedSheetCreator": true}'

// Specify updated user properties
var user = {
    "admin": true,
    "licensedSheetCreator": true
};

// Set options
var options = {
  id: 82349925918590, // Id of User
  body: user
    };

// Update user
smartsheet.users.updateUser(options)
    .then(function(updatedUser) {
        console.log(updatedUser)
    }).catch(function(error) {
        console.log(error);
    });

// Specify updated user properties
User userSpecification = new User
{
  Id = 82349925918590,
  Admin = true,
  LicensedSheetCreator = true
};

// Update user
User updatedUser = smartsheet.UserResources.UpdateUser(
  userSpecification
);

// Specify updated user properties
User userSpecification = new User();
userSpecification.setLicensedSheetCreator(true)
  .setAdmin(true)
  .setId(82349925918590L);        // long userId

// Update user
User updatedUser = smartsheet.userResources().updateUser(userSpecification);

updated_user = smartsheet_client.Users.update_user(
  82349925918590,     # user_id
  smartsheet.models.User({
    'licensed_sheet_creator': True,
    'admin': True
  })
)

# Specify updated user properties
body = {
  admin: false,
  licensed_sheet_creator: true,
  first_name: 'Johnny',
  last_name: 'Doeford',
  resource_viewer: true
}

# Update user
response = smartsheet.users.update(
  user_id: 48569348493401200,
  body: body
)
updated_user = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "admin": true,
    "licensedSheetCreator": true
  }
}

PUT /users/{userId}

Updates the user specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	User object containing at least one of the following attributes: admin (required) licensedSheetCreator (required) firstName (optional) groupAdmin (optional) lastName (optional) resourceViewer (optional)
Returns	Result object containing the User object for the updated user
Access Scope	ADMIN_USERS

Update User Profile Image

Example request: update user profile image

curl 'https://api.smartsheet.com/2.0/users/{userId}/profileimage' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: image/jpeg" \
-H 'Content-Disposition: attachment; filename=janeroe.jpg' \
-X POST \
--data-binary @janeroe.jpg

// Not yet implemented

// Not yet implemented

// Not yet implemented

# Not yet implemented

# Not yet implemented

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "email": "jane.roe@smartsheet.com",
    "name": "Jane Roe",
    "firstName": "Jane",
    "lastName": "Row",
    "profileImage": {
      "imageId": "u!1!nAtdn5RJB_o!k6_e_3h2R3w!wmYXPek-yVD",
      "height": 1050,
      "width": 1050
    },
    "id": 3173821341106052
  }
}

POST /users/{userId}/profileimage

Uploads an image to the user profile.

Headers	See Simple Uploads for information about required headers.
Request Body	Binary content for the file
Returns	Result object containing the User object for the updated user.
Access Scope	WRITE_SHEETS

Workspaces

Objects

Workspace Object

Example: Workspace object

{
  "sheets": [],
  "accessLevel": "OWNER",
  "id": 7116448184199044,
  "name": "New workspace",
  "permalink": "https://app.smartsheet.com/b/home?lx=8Z0XuFUEAkxmHCSsMw4Zgg"
}

id	number	Workspace Id
accessLevel	string	User's permissions on the workspace
favorite	Boolean	Returned only if the user has marked the workspace as a favorite in their "Home" tab (value = true)
folders	Folder[]	Array of Folder objects
name	string	Workspace name
permalink	string	URL that represents a direct link to the workspace 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 Workspace

Example request: copy workspace

curl 'https://api.smartsheet.com/2.0/workspaces/{workspaceId}/copy?include=data'
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
-H "Content-Type: application/json"
-d '{"newName": "newWorkspaceName"}'
-X POST

// Specify new workspace name
var body = {
  newName: "newWorkspaceName"
};

// Set elements to copy
var params = {
  include: "data,discussions",
  skipRemap: "cellLinks"
};

// Set options
var options = {
  workspaceId: 7116448184199044,
  body: body,
  queryParameters: params
};

// Copy workspace
smartsheet.workspaces.copyWorkspace(options)
  .then(function(copiedWorkspace) {
    console.log(copiedWorkspace);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify name for the new workspace
ContainerDestination destination = new ContainerDestination {
  NewName = "newWorkspaceName"
};

// Sample 1: Omit 'include' and 'skipRemap' parameters
Workspace workspace = smartsheet.WorkspaceResources.CopyWorkspace(
  7116448184199044,          // long workspaceId
  destination,
  null,                      // IEnumerable<WorkspaceCopyInclusion> include
  null                       // IEnumerable<WorkspaceRemapExclusion> skipRemap
);

// Sample 2: Specify 'include' parameter with value of "DATA", and 'skipRemap' parameter with value of "CELL_LINKS"
Workspace workspace = smartsheet.WorkspaceResources.CopyWorkspace(
  7116448184199044,           // long workspaceId
  destination,
  new WorkspaceCopyInclusion[] { WorkspaceCopyInclusion.DATA },
  new WorkspaceRemapExclusion[] { WorkspaceRemapExclusion.CELL_LINKS }
);

// Specify name for the new workspace
ContainerDestination destination = new ContainerDestination();
destination.setNewName("newWorkspaceName");

// Sample 1: Omit 'include' and 'skipRemap' parameters
Workspace workspace = smartsheet.workspaceResources().copyWorkspace(
  7116448184199044L,          // long workspaceId
  destination,
  null,                       // EnumSet<WorkspaceCopyInclusion> includes
  null                        // EnumSet<WorkspaceRemapExclusion> skipRemap
);

// Sample 2: Specify 'include' parameter with value of "DATA", and 'skipRemap' parameter with value of "CELLLINKS"
Workspace workspace = smartsheet.workspaceResources().copyWorkspace(
  7116448184199044L,          // long workspaceId
  destination,
  EnumSet.of(WorkspaceCopyInclusion.DATA),
  EnumSet.of(WorkspaceRemapExclusion.CELLLINKS)
);

new_workspace = smartsheet_client.Workspaces.copy_workspace(
  7116448184199044,           # workspace_id
  smartsheet.models.ContainerDestination({
    'new_name': 'newWorkspaceName'
  })
)

# Specify details
body = {
  new_name: 'newWorkspaceName'
}

# Copy workspace
response = smartsheet.workspaces.copy(
  workspace_id: 7116448184199044,
  body: body
)
new_workspace = response[:result]

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": 6282479888820100,
    "name": "newWorkspaceName",
    "accessLevel": "OWNER",
    "permalink": "https://{url}?lx=VL4YlIUnyYgASeX02grbLQ"
  }
}

POST /workspaces/{workspaceId}/copy

Creates a copy of the specified workspace.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Parameters	include (optional) -- comma-separated list of elements to copy: attachments cellLinks data -- includes formatting discussions -- includes comments filters forms ruleRecipients -- includes notification recipients, must also include rules when using this attribute rules -- includes notifications and workflow rules shares all - deprecated NOTE: Cell history is not copied, regardless of which include parameter values are specified.
	skipRemap (optional) -- comma-separated list of references to NOT re-map for the newly created workspace: cellLinks reports sheetHyperlinks sights By default, all cell links, reports, sheet hyperlinks, and Sights that reference objects in the source workspace are re-mapped to reference corresponding objects in the newly created workspace. 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 workspace continue to point to the original source sheets. If reports is specified in the skipRemap parameter value, the reports within the newly created workspace continue to point to the original source sheets. If sheetHyperlinks is specified in the skipRemap parameter value, the sheet hyperlinks within the newly created workspace 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 workspace continue to point to the original source sheets / reports.
Request Body	ContainerDestination object, limited to the following attribute: newName (string) - required
Returns	Result object containing a Workspace object for the newly created workspace
Access Scope	ADMIN_WORKSPACES

Create Workspace

Example request: create workspace

curl https://api.smartsheet.com/2.0/workspaces \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New workspace"}'

// Specify workspace name
var workspace = {"name": "New workspace"};

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

// Create workspace
smartsheet.workspaces.createWorkspace(options)
  .then(function(newWorkspace) {
    console.log(newWorkspace);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify workspace name
Workspace workspaceSpecification = new Workspace { Name = "New workspace" };

// Create workspace
Workspace newWorkspace = smartsheet.WorkspaceResources.CreateWorkspace(workspaceSpecification);

// Specify workspace name
Workspace workspaceSpecification = new Workspace();
workspaceSpecification.setName("New workspace");

// Create workspace
Workspace newWorkspace = smartsheet.workspaceResources().createWorkspace(workspaceSpecification);

workspace = smartsheet_client.Workspaces.create_workspace(
  smartsheet.models.Workspace({
    'name': 'New workspace'
  })
)

# Specify details
body = {
  name: 'New workspace'
}

# Create the workspace
response = smartsheet.workspaces.create(
  body: body
)
workspace = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "accessLevel": "OWNER",
    "id": 7960873114331012,
    "name": "New workspace",
    "permalink": "https://app.smartsheet.com/b/home?lx=rBU8QqUVPCJ3geRgl7L8yQ"
  }
}

POST /workspaces

Creates a workspace.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Workspace object, limited to the following attribute: name (string) - required
Returns	Result object containing a Workspace object for the newly created workspace
Access Scope	ADMIN_WORKSPACES

Delete Workspace

Example request: delete workspace

curl https://api.smartsheet.com/2.0/workspaces/7960873114331012 \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE

// Set options
var options = {
  workspaceId: 6621332407379844
};

// Delete workspace
smartsheet.workspaces.deleteWorkspace(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.WorkspaceResources.DeleteWorkspace(
  6621332407379844                // long workspaceId
);

smartsheet.workspaceResources().deleteWorkspace(
  6621332407379844L        // long workspaceId
);

smartsheet_client.Workspaces.delete_workspace(
  6621332407379844)       # workspace_id

smartsheet.workspaces.delete(
  workspace_id: 7116448184199044
)

Example response

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

DELETE /workspaces/{workspaceId}

Deletes the specified workspace (and its contents).

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WORKSPACES

Get Workspace

Example request: get workspace

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

// Set options
var options = {
  workspaceId: 7116448184199044
};

// Get workspace
smartsheet.workspaces.getWorkspace(options)
  .then(function(workspace) {
    console.log(workspace);
  })
  .catch(function(error) {
    console.log(error);
  });

// Sample 1: Omit 'loadAll' and 'include' parameters
Workspace workspace = smartsheet.WorkspaceResources.GetWorkspace(
  6621332407379844,           // long workspaceId
  null,                       // Nullable<bool> loadAll,
  null                        // IEnumerable<WorkspaceInclusion> include
);

// Sample 2: Specify 'loadAll' parameter with value of "false", and 'include' parameter with value of "source"
Workspace workspace = smartsheet.WorkspaceResources.GetWorkspace(
  6621332407379844,           // long workspaceId
  false,                      // Nullable<bool> loadAll,
  new WorkspaceInclusion[] { WorkspaceInclusion.SOURCE }
);

// Sample 1: Omit 'loadAll' and 'include' parameters
Workspace workspace = smartsheet.workspaceResources().getWorkspace(
  6621332407379844L,      // long workspaceId
  null,                   // Boolean loadAll
  null                    // EnumSet<SourceInclusion> includes
);

// Sample 2: Specify 'loadAll' parameter with value of "false", and 'include' parameter with value of "source"
Workspace workspace = smartsheet.workspaceResources().getWorkspace(
  6621332407379844L,      // long workspaceId
  false,                  // Boolean loadAll
  EnumSet.of(SourceInclusion.SOURCE)
);

workspace = smartsheet_client.Workspaces.get_workspace(
  6621332407379844)       # workspace_id

response = smartsheet.workspaces.get(
  workspace_id: 7116448184199044
)

Example response

{
  "sheets": [
    {
      "id": 4583173393803140,
      "name": "sheet 1",
      "accessLevel": "OWNER",
      "permalink": "https://app.smartsheet.com/b/home?lx=8Z0XuFUEAkxmHCSsMw4Zg1",
      "createdAt": "2015-06-05T20:05:29Z",
      "modifiedAt": "2015-06-05T20:05:43Z"
    }
  ],
  "accessLevel": "OWNER",
  "id": 7116448184199044,
  "name": "New workspace",
  "permalink": "https://app.smartsheet.com/b/home?lx=8Z0XuFUEAkxmHCSsMw4Zgg"
}

GET /workspaces/{workspaceid}

Gets the specified workspace (and lists its contents).

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters	loadAll (optional) -- true or false (defaults to false)
	include (optional) -- a comma-separated list of optional elements to include in the response: ownerInfo - owner's email address and user Id for each sheet source - the Source object for any sheet that was created from another report, sheet, Sight (aka dashboard), or template, if any sheetVersion - current version number of each sheet
Returns	Workspace object, populated according to the include parameter
Access Scope	READ_SHEETS

List Workspaces

Example request: list workspaces

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

smartsheet.workspaces.listWorkspaces()
    .then(function(workspaceList) {
        console.log(workspaceList);
    })
    .catch(function(error) {
        console.log(error);
    });

// Omit pagination parameters
PaginatedResult<Workspace> workspaces = smartsheet.WorkspaceResources.ListWorkspaces(
  null                // PaginationParameters
);

// Omit pagination parameters
PagedResult<Workspace> workspaces = smartsheet.workspaceResources().listWorkspaces(
  null        // PaginationParameters
);

# Sample 1: List all
response = smartsheet_client.Workspaces.list_workspaces(include_all=True)
workspaces = response.data

# Sample 2: Paginate the list
response = smartsheet_client.Workspaces.list_workspaces(
  page_size=20,
  page=1)
pages = response.total_pages
workspaces = response.data

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

Example response

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
    "data": [
        {
            "accessLevel": "OWNER",
            "id": 3457273486960516,
            "name": "workspace 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=JNL0bgXtXc0pzni9tzAc4g"
        },
        {
            "accessLevel": "OWNER",
            "id": 7960873114331012,
            "name": "workspace 2",
            "permalink": "https://app.smartsheet.com/b/home?lx=JLiJbgXtXc0pzni9tzAKiR"
        }
    ]
}

GET /workspaces

Gets a list of workspaces that the user has access to. The list contains an abbreviated Workspace object for each 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 Workspace objects
Access Scope	READ_SHEETS

Share Workspace

For details about workspace sharing, see Workspace Sharing.

Update Workspace

Example request: update workspace

curl https://api.smartsheet.com/2.0/workspaces/7960873114331012 \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name": "Updated workspace"}'

// Specify updated workspace properties
var workspace = {"name": "Updated workspace"};

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

// Update workspace
smartsheet.workspaces.updateWorkspace(options)
  .then(function(updatedWorkspace) {
    console.log(updatedWorkspace);
  })
  .catch(function(error) {
    console.log(error);
  });

// Specify updated workspace name
Workspace workspaceSpecification = new Workspace
{
  Id = 7960873114331012,
  Name = "Updated Workspace"
};

// Update workspace
Workspace updatedWorkspace = smartsheet.WorkspaceResources.UpdateWorkspace(
  workspaceSpecification
);

// Specify updated workspace properties
Workspace workspaceSpecification = new Workspace();
workspaceSpecification.setName("Updated workspace")
  .setId(7960873114331012L);

// Update workspace
Workspace updatedWorkspace = smartsheet.workspaceResources().updateWorkspace(workspaceSpecification);

updated_workspace = smartsheet_client.Workspaces.update_workspace(
  7960873114331012,       # workspace_id
  smartsheet.models.Workspace({
    'name': 'Updated workspace'
  })
)

# Specify updated workspace properties
body = {
  name: 'Updated workspace'
}

# Update workspace
response = smartsheet.workspaces.update(
  workspace_id: 7960873114331012,
  body: body
)

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "accessLevel": "OWNER",
    "id": 7960873114331012,
    "name": "Updated workspace",
    "permalink": "https://app.smartsheet.com/b/home?lx=rBU8QqUVPCJ3geRgl7L8yQ"
  }
}

PUT /workspaces/{workspaceId}

Updates the workspace specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Workspace object limited to the following attribute: name (string)
Returns	Result object containing the updated Workspace object
Access Scope	ADMIN_WORKSPACES

Related Items

Workspace Folders

For details about working with folders in a workspace, see Folders.

Workspace Sheets

For details about working with sheets in a workspace, see Sheets.

Additional Reference

Other Objects

AutoNumberFormat Object

Example: AutoNumberFormat object

{
  "prefix": "ITEM-",
  "fill": "0000",
  "suffix": ""
}

Object that describes how the the System Column type of "AUTO_NUMBER" is auto-generated.

fill	string	Indicates zero-padding. Must be between 0 and 10 "0" (zero) characters.
prefix	string	The prefix. Can include the date tokens: {YY} {YYYY} {MM} {DD}
startingNumber	number	The starting number for the auto-id
suffix	string	The suffix. Can include the date tokens: {YY} {YYYY} {MM} {DD}

BulkItemFailure Object

Example: BulkItemFailure object

{
  "index": 0,
  "rowId": 564480076736388,
  "error": {
    "errorCode": 1042,
    "message": "The value for cell in column 647615814625156, Mad Hatter, did not conform to the strict requirements for type PICKLIST.",
    "refId": "136g6zxtcekx2"
  }
}

Object that contains information about an item that failed to be added or updated as specified by a bulk request.

rowId	number	The id of the Row that failed. Applicable only to bulk row operations
error	Error object	The error caused by the failed item
index	number	The index of the failed item in the bulk request array

ContainerDestination Object

Example: ContainerDestination object

{ 
  "destinationType": "folder", 
  "destinationId": 6137362003584900,
  "newName": "New folder"
}

Object that describes the destination container when a Sheet or Folder is moved, or when a Sheet, Folder, or Workspace is copied.

destinationId	number	Id of the destination container (when copying or moving a Sheet or a Folder). Required if destinationType is "folder" or "workspace" If destinationType is "home", this value must be null.
destinationType	string	Type of the destination container (when copying or moving a Sheet or a Folder). One of the following values: home workspace folder
newName	string	Name of the newly created object (when creating a copy of a Sheet, Folder, Sight, or Workspace). This attribute is not supported for "move" operations (that is, a moved Sheet, Folder, Sight, or Workspace retains its original name).

Error Object

Example: Error object

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

refId	string	Id of the specific error occurrence. Please include this information when contacting Smartsheet support.
errorCode	number	Custom error code from Smartsheet. See the Complete Error Code List.
message	string	Descriptive message.

IndexResult Object

Example: IndexResult object

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": []
}

Object returned for all GET operations against index endpoints. This object provides metadata which can be used to perform paging on potentially large data sets. See the Paging section for more information.

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.

Result Object

Example: Result object

{
  "message": "PARTIAL_SUCCESS",
  "resultCode": 3,
  "result": [],
  "version": 14,
  "failedItems": []
}

Object returned for all PUT operations and POST operations (and for some other operations).

failedItems	BulkItemFailure[]	Array of BulkItemFailure objects which represents the items that failed to be added or updated. See Partial Success for more information. Applicable only for bulk operations that support partial success
message	string	Message that indicates the outcome of the request. (One of SUCCESS or PARTIAL_SUCCESS)
result	Object	Object that was created or updated (if applicable)
resultCode	number	0 (zero) if successful, 3 for partial success of a bulk operation.
version	number	New version of the Sheet. Applicable only for operations which update sheet data

Complete Error Code List

For an explanation of the logic behind Smartsheet error codes and error handling, see the HTTP and REST portion of the Introduction.

400-Level Error Codes

400-level error codes generally indicate that there is something you should fix or add to your request before you try the request again.

HTTP status code	Smartsheet errorCode	Smartsheet message
401	1001	An Access Token is required.
401	1002	Your Access Token is invalid.
401	1003	Your Access Token has expired.
403	1004	You are not authorized to perform this action.
401	1005	Single Sign-On is required for this account.
404	1006	Not Found.
404	1007	Version not supported.
400	1008	Unable to parse request. The following error occurred: {0}
400	1009	A required parameter is missing from your request: {0}.
405	1010	HTTP Method not supported.
400	1011	A required header was missing or invalid: {0}
400	1012	A required object attribute is missing from your request: {0}.
403	1013	The operation you are attempting to perform is not supported by your plan.
403	1014	There are no licenses available on your account.
403	1015	The user exists in another account. The user must be removed from that account before they can be added to yours.
403	1016	The user is already a member of your account.
403	1017	The user already has a paid account. The user must cancel that account before they can be added to yours.
400	1018	The value {0} was not valid for the parameter {1}.
400	1019	Cannot transfer to the user specified. User not found.
404	1020	User not found.
403	1021	Cannot transfer to the user specified. They are not a member of your account.
403	1022	Cannot delete the user specified. They are not a member of your account.
400	1023	The sheet specified is shared at the Workspace level.
400	1024	The HTTP request body is required for this Method.
400	1025	The share already exists.
403	1026	Transferring ownership is not currently supported.
404	1027	Share not found.
400	1028	You cannot edit the share of the owner.
400	1029	The parameter in the URI does not match the object in the request body.
401	1030	You are unable to assume the user specified.
400	1031	The value {0} was not valid for the attribute {1}.
400	1032	The attribute(s) {0} are not allowed for this operation.
404	1033	The template was not found.
400	1034	Invalid Row Id.
400	1035	Attachments and discussions cannot be POSTed with a row.
400	1036	The columnId {0} is invalid.
400	1037	The columnId {0} is included more than once in a single row.
400	1038	Invalid Cell value. Must be numeric or a string.
403	1039	Cannot edit a locked column {0}.
400	1040	Cannot edit your own share.
400	1041	The value for {0} must be {1} characters in length or less, but was {2}.
400	1042	The value for cell in column {0}, {1}, did not conform to the strict requirements for type {2}.
404	1043	The row number you requested is blank and cannot be retrieved.
400	1044	Assume-User header is required for your Access Token.
403	1045	The resource specified is read-only.
400	1046	Cells containing formulas, links to other cells, system values, or Gantt values cannot be inserted or updated through the API.
403	1047	You cannot remove yourself from the account through the API.
403	1048	The user specified has declined the invitation to join your organization. You cannot modify declined invitations.
403	1049	You cannot remove admin permissions from yourself through the API.
403	1050	You cannot edit a locked row.
400	1051	Attachments of type FILE cannot be created using JSON.
406	1052	Invalid Accept header. Media type not supported.
400	1053	Unknown Paper size: {0}.
400	1054	The new sheet requires either a fromId or columns.
400	1055	One and only one column must be primary.
400	1056	Column titles must be unique.
400	1057	Primary columns must be of type TEXT_NUMBER.
400	1058	Column type of {1} does not support symbol of type {0}.
400	1059	Column options are not allowed when a symbol is specified.
400	1060	Column options are not allowed for column type {0}.
400	1061	Max count exceeded for field {0}.
400	1062	Invalid row location.
400	1063	Invalid parentId: {0}.
400	1064	Invalid siblingId: {0}.
400	1065	The column specified cannot be deleted.
400	1066	You can only share to {0} users at a time.
401	1067	Invalid client_id
400	1068	Unsupported grant type.
400	1069	Invalid Request. The authorization_code has expired.
400	1070	Invalid Request. Required parameter is missing: {0}.
400	1071	Invalid Grant. The authorization code or refresh token provided was invalid.
400	1072	Invalid hash value. The hash provided did not match the expected value.
400	1073	The redirect_uri did not match the expected value.
400	1074	You are trying to upload a file of {0}, but the API currently only supports {1}.
400	1075	The Content-Size provided did not match the file uploaded. This may be due to network issues or because the wrong Content-Size was specified.
403	1076	The user has created sheets and must be added as a licensed user.
400	1077	Duplicate system column type: {0}.
400	1078	System column type {0} not supported for {1} {2}.
400	1079	Column type {0} is not supported for system column type {1}.
400	1080	End Dates on dependency-enabled sheets cannot be created/updated. Please update either the Duration or Start Date column.
403	1081	You cannot delete or update another user's discussions, comments, or comment attachments.
400	1082	You cannot add options to the given column {0} because it is not a PICKLIST.
400	1083	Auto number formatting cannot be added to a column {0}.
400	1084	The auto number format is invalid.
400	1085	To change this column's type you must first disable Dependencies for this sheet.
400	1086	Google was not able to verify your access.
400	1087	The column specified is used in a conditional formatting rule, so the column cannot be deleted and its type cannot be changed.
400	1088	Invalid length for concatenated auto number format. Concatenated format is {0}, with a length of {1}. Must be less than or equal to 40.
400	1089	The type specified is only used with System Columns.
400	1090	Column.type is required when changing symbol, systemColumnType or options.
400	1091	Invalid Content-Type: {0}.
403	1092	You cannot delete this row. Either it or one or more of its children are locked.
400	1095	The Excel file is invalid/corrupt. This may be due to an invalid file extension, an outdated Excel format, or an invalid Content-Length.
403	1096	This Apple payment receipt has already been applied to a user's payment profile.
403	1097	A user must be a licensed sheet creator to be a resource viewer.
400	1098	To delete this column you must first disable Dependencies for this sheet.
400	1099	To delete this column you must first disable Resource Management for this sheet.
400	1100	Uploading new versions of a discussion comment attachment is not supported.
400	1101	Uploading new versions of non-FILE type attachments is not supported.
403	1102	A user must be a licensed sheet creator to be a group administrator.
400	1103	A group with the same name already exists.
403	1104	You must be a group administrator to create a group.
400	1105	The operation failed because one or more group members were not members of your account: {0}.
404	1106	Group not found.
400	1107	User specified in transferGroupsTo must be a group admin.
400	1108	transferGroupsTo must be provided because user being deleted owns one or more groups.
400	1109	Only one of cell.hyperlink or cell.linkInFromCell may be non-null.
400	1110	cell.value must be null if cell.linkInFromCell is non-null.
400	1111	Only one of cell.hyperlink.sheetId and cell.hyperlink.reportId may be non-null.
400	1112	cell.hyperlink.url must be null for sheet or report hyperlinks.
400	1113	cell.value must be a string when the cell is a hyperlink.
404	1114	Invalid sheetId or reportId: {0}.
400	1115	Row must contain either cell link updates or row/cell value updates; mixing of both update types in one API call is not supported.
400	1116	You cannot link a cell to its own sheet.
400	1117	One of the following cell.hyperlink fields must be non-null: url, sheetId, or reportId.
400	1118	You cannot set the value of a Gantt allocation column (id {0}) in a row that has child rows.
400	1120	Too many sheets to copy. NOTE: includes a "detail" object containing "maxSheetCount" which represents the server-side limit on the number of sheets allowed in a single folder/workspace copy operation.
400	1121	transferTo must be provided because user being deleted owns one or more groups.
405	1122	Requested URL does not support this method: {0}.
400	1123	Specifying multiple row locations is not yet supported. Each row must use the same row location attribute and value (toBottom, toTop, parentId, siblingId, above).
415	1124	Invalid Content-Type header. Media type not supported.
400	1125	Each part in a multipart payload must have a name.
400	1126	Multipart payload contained duplicate part names: {0}.
400	1127	Required multipart part was missing: '{0}'
400	1128	Multipart upload size limit exceeded.
400	1129	The resource you tried to create already exists.
400	1130	One of cell.value or objectValue may be set, but not both.
400	1131	cell.{0} for column {1} was of the wrong object type. Allowed types: {2}.
400	1132	The token provided has previously been revoked.
400	1133	Column titles are not unique among input columns.
400	1134	Duplicate system column type among input columns.
400	1135	Input column index {0} is different from the first input column index {1}.
400	1136	Cannot copy or move row(s) within the same sheet.
400	1137	Input collection contains multiple instances of the same element.
403	1138	The user is not eligible for a trial organization.
403	1139	The user is an admin in another organization. Add 'allowInviteAccountAdmin=true' to the query string to invite their entire organization.
403	1140	The user must be added as a licensed user.
403	1141	Inviting users from an enterprise organization is not supported.
400	1142	Column type {0} is reserved for project sheets and may not be manually set on a column.
400	1143	To set {0}, you must first enable dependencies on the sheet.
400	1144	The user owns one or more groups and must be added as a Group Admin.
400	1145	Multipart upload request was invalid. Please check your request headers and payload.
400	1146	Unsupported operation: {0}.
400	1147	Multipart request contained an invalid part name: '{0}'
400	1148	Numeric cell values must be between {0} and {1}.
400	1155	You cannot set the '{0}' attribute for a cell in a 'Project Settings' column of a dependency-enabled sheet.
400	1156	Invalid email.
400	1157	This address is already associated with another Smartsheet account, so it cannot be added as an alternate address for this account.
400	1158	This address has not been confirmed yet, so it can't be set as the primary email address.
400	1159	The specified email address ({0}) is an alternate email address for a user with a primary email address of {1}.
400	1160	Invalid bulk request. See detail for more information.
400	1161	Cannot set altText for a cell that does not contain an image: row {0}, column {1}.
400	1163	If cell.image is non-null then value, objectValue, hyperlink, and linkInFromCell must all be null.
400	1164	Cannot add image to cell because this feature has been disabled by the org administrator.
400	1165	Cannot add image to cell with alt text larger than 100 characters.
400	1166	You cannot share Sights as an Editor.
400	1167	The resource you are attempting to access has expired.
403	1173	You must be in a Team/Enterprise account to specify a {0} value of '{1}'.
403	1174	The value for {0} is invalid because this publish option is configured to be restricted to users in this account.
403	1175	One or more publish options which you attempted to enable are disabled for this account.
400	1176	Array attribute(s) may not contain null elements: {0}.
400	1177	Arrays may not contain null elements.
400	1178	The following combination of attributes is not allowed for this operation: {0}.
400	1179	The schedule specified is invalid because endAt is earlier than the next send date.
403	1180	We are unable to process this request because the email has been associated with a different Smartsheet account.
403	1181	Only admins can edit shared filters.
400	1182	The specified sheet filter {0} does not exist for sheet {1}.
400	1183	Sheet filters must define at least one detail entry.
400	1184	Sheet {0} already has a filter named '{1}' of type {2}.
400	1185	Cannot create a child of a parent row that has no data in it.
403	1186	User's primary email address must be a validated domain.
403	1187	User's alternate address selected to be made primary must be a validated domain.
403	1188	The account status of the user specified is not active.
400	1189	Only Enterprise or Team accounts with security controls are able to change primary emails.
400	1190	Only Enterprise or Team accounts with special permission granted are able to change primary emails.
400	1210	Column validation is not supported for column type '{0}'.
400	1211	Not authorized.
403	1212	You must be a sheet admin to override validation.
400	1213	A(n) {0} could not be saved to column "{1}" since column validation is enabled as type "{2}".
400	1214	Dropdown and Contact List columns with data validation must have at least one option value.
400	1218	The attributes recipientColumnIds, recipients and notifyAllSharedUsers are mutually exclusive. Only one may be set, not all.
400	1218	The attributes includeAllColumnIds and includedColumnIds are mutually exclusive. Only one may be set not all.
400	1219	Some recipients cannot be notified. They are not shared to the sheet, or your settings prohibit notification of non-shared users.
400	1220	Automation action type cannot be changed.
400	1221	The value {0} is not valid for the attribute action.recipientColumnIds. Only Contact List columns may be used.
400	1227	The query parameters '{0}' and '{1}' are mutually exclusive. Only one may be set.
400	1228	You must specify one of the following query parameters: '{0}' or '{1}'.
400	1229	The value '{0}' was not valid for the parameter '{1}'. The value must be between '{2}' and '{3}'.
400	1255	Attachment type '{0}' is not supported.
400	1266	This rule is not accessible through the API. Only single-action notifications, approval requests, or update requests qualify.
429	4003	Rate limit exceeded.
400	5xxx	Errors in the 5xxx range represent conditions that a developer cannot reasonably prevent or handle, most typically related to account status. These error messages are localized and can be displayed to the end-user to inform them of the condition that caused the error to occur.

500-Level Error Codes

500-level error codes indicate there is some kind of permanent error.

HTTP status code	Smartsheet errorCode	Smartsheet message
500	1006	Not found.
500	1012	Required object attribute(s) are missing from your request: action.includedColumnIds.
500	1031	The value '[]' is not valid for the attribute action.includedColumnIds.
500	1032	The attribute(s) automationRule.userCanModify are not allowed for this operation.
500	1119	Failed to complete copy. NOTE: may include a "detail" object containing "topContainerType" and "topContainerId" which represent the top-level folder or workspace that were partially copied.
500	1170	The sheet referenced by this widget is unavailable or deleted.
500	1171	The report referenced by this widget is unavailable or deleted.
500	1172	The referenced cell is unavailable or deleted.
500	1222	The value '{0}' was not valid for the operation. {1}
500	4000	An unexpected error has occurred. Please contact api@smartsheet.com for assistance.
503	4001	Smartsheet.com is currently offline for system maintenance. Please check back again shortly.
500	4002	Server timeout exceeded. Request has failed.
500	4004	An unexpected error has occurred. Please retry your request. If you encounter this error repeatedly, please contact api@smartsheet.com for assistance. Or Request failed because sheetId {0} is currently being updated by another request that uses the same access token. Please retry your request once the previous request has completed.
500	5151	The action could not be completed because the following people are outside of the approved domain sharing list:[email address]
500	5502	You must have sheet admin permission to save a notification with recipients other than yourself.

Formatting

To set or read formatting programmatically, Smartsheet uses a compact format string, cell.format, which looks something like this: ",,1,1,,,,,,,,,,,,,". The position and sample values in this string are explained in the following format descriptor table:

Format Descriptor Table

Position	Lookup Property	Example Value	Format String
0	fontFamily	0 = Arial, default	"0,,,,,,,,,,,,,,,,"
1	fontSize	0 = 8 pt, default	",0,,,,,,,,,,,,,,,"
2	bold	1 = on	",,1,,,,,,,,,,,,,,"
3	italic	1 = on	",,,1,,,,,,,,,,,,,"
4	underline	1 = on	",,,,1,,,,,,,,,,,,"
5	strikethrough	1 = on	",,,,,1,,,,,,,,,,,"
6	horizontalAlign	2 = center	",,,,,,2,,,,,,,,,,"
7	verticalAlign	2 = middle	",,,,,,,2,,,,,,,,,"
8	color (text)	4 = #FEEEF0	",,,,,,,,4,,,,,,,,"
9	color (background)	8 = #E6F5FE	",,,,,,,,,8,,,,,,,"
10	color (taskbar)	9 = #F3E5FA	",,,,,,,,,,9,,,,,,"
11	currency	13 = USD	",,,,,,,,,,,13,,,,,"
12	decimalCount	3 = three decimal places	",,,,,,,,,,,,3,,,,"
13	thousandsSeparator	1 = on	",,,,,,,,,,,,,1,,,"
14	numberFormat	2 = currency	",,,,,,,,,,,,,,2,,"
15	textWrap	1 = on	",,,,,,,,,,,,,,,1,"
16	dateFormat	1 = mmmm d yyyy (December 8, 1997)	",,,,,,,,,,,,,,,,1"

Objects

FormatTables Object

Example: FormatTables object

{
  "defaults": "0,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0",
  "fontFamily": [{
          "name": "Arial",
          "traits": [ "sans-serif" ]
      } // ...
  ],
  "fontSize": [ "8", "9" // ...
  ],
  "bold": [ "none", "on" ],
  "italic": [ "none",  "on" ],
  "underline": [ "none",  "on" ],
  "strikethrough": [ "none",  "on" ],
  "horizontalAlign": [ "default", "left"  // ...
  ],
  "verticalAlign": [ "default", "top" // ...
  ],
  "color": [ "none", "#000000" // ...
  ],
  "currency": [
      { "code": "none", "symbol": "none"  },
      { "code": "USD",  "symbol": "$" }
      // ...
  ],
  "decimalCount": [ "0", "1" // ... 
  ],
  "thousandsSeparator": [ "none",  "on" ],
  "numberFormat": [ "none", "NUMBER" // ...
  ],
  "textWrap": [ "none",  "on" ]
}

Contains all of the lookup tables that the format descriptor indexes refer to.

defaults	A format descriptor where each element describes the formats the Smartsheet Web app displays for format values that have not been set.
bold	Possible values: none or on
color	Color hex values. NOTE: none is the default value for all colors. Applications must handle this value and use app-defined colors (typically this is Black for text color and White for background color)
currency	Currency codes and symbols
dateFormat	Array of strings containing available date formats
decimalCount	All allowed decimal count values
fontFamily	Font families with additional font information
fontSize	Font sizes in points
horizontalAlign	Horizontal alignment, possible values: default center left right NOTE: default is the default value, which is equivalent to left.
italic	Possible values: none or on
numberFormat	Possible values: none CURRENCY NUMBER PERCENT
strikethrough	Possible values: none or on
textWrap	Possible values: none or on
thousandsSeparator	Possible values: none or on
underline	Possible values: none or on
verticalAlign	Vertical alignment, possible values: default bottom middle top NOTE: default is the default value, which is equivalent to top.

FontFamily Object

Example: FontFamily object

{
  "fontFamily": [{
    "name": "Arial",
      "traits": [
        "sans-serif"
    ]
  }]
}

name	string	Name of the font family (for example, "Arial")
traits	array	Platform-independent traits of the font family. One of the following values: serif or sans-serif

Currency Object

Example: Currency object

{
    "currency": [{
        "code": "USD",
        "symbol": "$"
    }]
}

code	string	The ISO 4217 currency code (for example, "EUR")
symbol	string	The currency symbol (for example, "€")

Get Formatting

Use the "include=format" query-string parameter on API operations that return detailed objects, such as GET /sheets/{sheetId} or GET sheets/{sheetId}/rows/{rowId}. If there is formatting other than default settings, the return includes a format property. If an object has conditional formatting, the format property returned will have a conditionalFormat value.

Set Formatting for a Row or Column

Setting the format of a row object or column object through the API simply sets the baseline format for new or blank cells in that row or column. It does not affect cells that already have a value.

If you want to change the formatting of cells that already have content, for instance you want to make a row bold, then you have to set the format for each cell individually.

Troubleshooting

Should you encounter issues with the Smartsheet API while building an integration using a particular programming language (ex: Java, C#, PHP, Python, etc.), keep the following troubleshooting techniques in mind.

1. Try executing the same API Request using a tool like cURL or Postman. By taking your code out of the equation, you can isolate troubleshooting to the raw Request / Response.
   • If you receive a similar error when you execute the Request using cURL or Postman, this suggests an issue with the Request format or contents. Once you have the Request working in cURL or Postman, update your code accordingly.
   • If you can execute the Request successfully using cURL or Postman, but not via your code, this suggests that the Request your code is sending is somehow different than what you intend. Compare the (successful) Request from cURL or Postman with the (unsuccessful) Request that your code generates. (See step #2 below.)
2. Examine the Request that your code is sending (including the HTTP verb, URI, headers, and Request body) and the Response that it's receiving back from Smartsheet (including the HTTP status code, headers, and response body).
   • If you've implemented Request / Response logging in your application, inspect the full trace of Request and Response in the log file. Compare the Request that your application is logging with the (successful) Request from cURL or Postman, and update your code to correct any discrepancies.
   • Alternatively, you may choose to use a tool like Fiddler or Charles HTTP Proxy to inspect the full trace of Request and Response as it goes across the wire. Compare the Request trace that your application generates with the (successful) Request from cURL or Postman, and update your code to correct any discrepancies.
3. Check for capitalization errors. NOTE: URL endpoints are all lower case, while object properties and query parameters are camelCase.

Event Reporting

The following section describes the specific event types and payloads returned from the Smartsheet Events API.

With Event Reporting, you can programmatically retrieve events that are occurring in your Smartsheet organization account. Examples of events are create, update, load, and delete of sheets, reports, dashboards, attachments, and users. Note: while the current list of events covers most of Smartsheet functionality, new events will be added to the list as Smartsheet introduces new functionality.

See Event Reporting reference documentation for details on each event type.

See Authentication and Access Tokens for more information.

Objects

Event Object

Example: Event object

{
  "eventId" : "4b12345abc444def333g149he2b15b3j",
  "objectType" : "SHEET",
  "action" : "CREATE",
  "objectId" : 345678901234,
  "eventTimestamp" : "2019-04-29T08:28:33Z",
  "userId" : 123457654321,
  "requestUserId" : 133445566778,
  "source" : "WEB_APP",
  "additionalDetails" : {
    "sheetName" : "Test Sheet"
  }
}

eventId	string	Unique event identifier.
objectType	string	The Smartsheet resource impacted by the event, such as, SHEET or WORKSPACE.
action	string	The action applied to the specified object, such as CREATE or DELETE.
objectId	string or long	The identifier of the object impacted by the event.
eventTimestamp	string	Date and time of the event. Defaults to ISO-8601 format. See dates and times for more information.
userId	long	User assumed as the one who initiated the event. Usually the userId property and the requestUserId property (below) have the same value. However, if the request is an API call with Assume-User header then the userId property identifies the user whose email matches the value in the Assume-User header.
requestUserId	long	User whose authentication credential is embedded in the request that initiated the event. For example, if the request is an API call with an access token then requestUserId identifies the user whose data can be accessed via the access token (i.e., the user who authorized the creation of the access token). On the other hand, if the request comes from a UI session, then requestUserId identifies the user logged-in to the UI.
accessTokenName	string	Name of the access token embedded in the request. This property is omitted if there is no access token in the request (i.e., it isn't an API call) or if the access token wasn't given a name when created (only access tokens generated via the Smartsheet desktop UI can be given a name at creation time).
source	string	Identifies the type of action that triggered the event.
additionalDetails	object	Container object for additional event-specific properties. Properties depend upon the event type. See Event Reporting reference documentation for details on each event type.

StreamResult Object

Example: StreamResult object

{
  "nextStreamPosition": "XyzAb1234cdefghijklmnofpq",
  "moreAvailable": "false",
  "data": []
}

nextStreamPosition	string	This string should be passed back to the next GET events call to obtain subsequent events
moreAvailable	Boolean	True if more results are available. This is typically due to event counts exceeding the maxCount parameter passed in
data	Event[]	Array of event information.

Get Events

Example request: get events

// Example 1: Return events starting from the oldest event available
curl https://api.smartsheet.com/2.0/events?since=2010-01-01T00:00:00Z \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Accept-Encoding: gzip"

// Example 2: Return events from a given stream position on
curl https://api.smartsheet.com/2.0/events?streamPosition=XyzAb1234cdefghijklmnofpq \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Accept-Encoding: gzip"

// Initialize the client
var client = require('smartsheet');
var smartsheet = client.createClient({
  accessToken: '1234',
  logLevel: 'info'
});

const currentDate = new Date();
const dateWeekAgo = currentDate.setDate(currentDate.getDate() - 7);
// The first call to the events reporting API
// requires the since query parameter.
// If you pass in an UNIX epoch date, numericDates must be true
let options = {
  queryParameters: {
    since: dateWeekAgo,
    maxCount: 10,
    numericDates: true
  }
}

function getEvents(options) {
  smartsheet.events.getEvents(options)
  .then((result) => {
    printNewSheetEvents(result);
    getNextStreamOfEvents(result.moreAvailable, result.nextStreamPosition);
  })
  .catch((error) => console.log(JSON.stringify(error)));
}

function getNextStreamOfEvents(moreEventsAvailable, nextStreamPosition) {
  // Subsequent calls require the streamPosition property
  options = {
    queryParameters: {
      streamPosition: nextStreamPosition,
      maxCount: 10
    }
  }

  if (moreEventsAvailable) {
    getEvents(options);
  } 
}

// This example is looking specifically for new sheet events
function printNewSheetEvents(result) {
  // Find all created sheets
  result.data.forEach(function (item) {
    if (item.objectType === "SHEET" && item.action === "CREATE") {
      console.log(item.additionalDetails.sheetName)
    }
  })
}

getEvents(options);

class Program
{
  // This example is looking specifically for new sheet events
  private static void PrintNewSheetEventsInList(IList<Event> events)
  {
    //  enumerate all events in the list of returned events
    foreach (Event _event in events)
    {
      // find all created sheets
      if (_event.ObjectType == EventObjectType.SHEET && _event.Action == EventAction.CREATE)
      {
        // additional details are available for some events, they can be accessed as a Dictionary
        // in the AdditionalDetails property
        if (_event.AdditionalDetails.ContainsKey("sheetName"))
        {
          Console.WriteLine(_event.AdditionalDetails["sheetName"]);
        }
      }
    }
  }

  static void Main(string[] args)
  {
    // Initialize client
    SmartsheetClient smartsheet = new SmartsheetBuilder().Build();

    // Begin listing events in the stream starting with the `since` parameter
    DateTime lastWeek = DateTime.Today.AddDays(-7);
    // This example looks at the previous 7 days of events by providing a since argument set to last week's date 
    EventResult eventResult = smartsheet.EventResources.ListEvents(lastWeek, null, 1000, false);
    PrintNewSheetEventsInList(eventResult.Data);

    // Continue listing events in the stream by using the `StreamPosition`, if the previous response indicates 
    // that more data is available.
    while(eventResult.MoreAvailable == true)
    {
      eventResult = smartsheet.EventResources.ListEvents(null, eventResult.NextStreamPosition, 10000, true);
      PrintNewSheetEventsInList(eventResult.Data);
    }
  }
}

public class Sample {

  public static void main(String[] args) throws SmartsheetException {
    SampleProgram();
  }

  // This example is looking specifically for new sheet events
  private static void printNewSheetEventsInList(List<Event> events)
  {
    //  Enumerate all events in the list of returned events
    for(Event event: events) {
      // find all created sheets
      if(event.getObjectType() == EventObjectType.SHEET && event.getAction() == EventAction.CREATE) {
        // additional details are available for some events, they can be accessed as a HashMap
        // in the additionalDetails property
        System.out.println(event.getAdditionalDetails().get("sheetName"));
      }
    }
  }

  public static void SampleProgram() throws SmartsheetException{

    Smartsheet smartsheet = SmartsheetFactory.createDefaultClient();

    // Begin listing events in the stream starting with the `since` parameter
    Date lastWeek = new Date(System.currentTimeMillis() - TimeUnit.DAYS.toMillis(7));
    // this example looks at the previous 7 days of events by providing a since argument set to last week's date 
    EventResult eventResult = smartsheet.eventResources().listEvents(lastWeek, null, 1000, false);
    printNewSheetEventsInList(eventResult.getData());

    // Continue listing events in the stream by using the `streamPosition`, if the previous response indicates 
    // that more data is available.
    while(eventResult.getMoreAvailable()) {
      eventResult = smartsheet.eventResources().listEvents(null, eventResult.getNextStreamPosition(), 10000, true);
      printNewSheetEventsInList(eventResult.getData());
    }
  }
}

# This example is looking specifically for new sheet events
def print_new_sheet_events_in_list(events_list):
  # Enumerate all events in the list of returned events
  for event in events_list.data:
    # Find all created sheets
    if event.object_type == smartsheet.models.enums.EventObjectType.SHEET and event.action == smartsheet.models.enums.EventAction.CREATE:
        # Additional details are available for some events, they can be accessed as a Python dictionary
        # in the additional_details attribute
        print(event.additional_details['sheetName'])

smartsheet_client = smartsheet.Smartsheet()
smartsheet_client.errors_as_exceptions()

# Begin listing events in the stream starting with the `since` parameter
last_week = datetime.now() - timedelta(days=7)
# This example looks at the previous 7 days of events by providing a `since` argument set to last week's date in ISO format
events_list = smartsheet_client.Events.list_events(since=last_week.isoformat(), max_count=1000)
print_new_sheet_events_in_list(events_list)

# Continue listing events in the stream by using the stream_position, if the previous response indicates that more 
# data is available.
while events_list.more_available:
  events_list = smartsheet_client.Events.list_events(stream_position=events_list.next_stream_position, max_count=10000,
                                      numeric_dates=True)
  print_new_sheet_events_in_list(events_list)

require 'smartsheet'
require 'time'
require 'date'
require 'pp'

# Initialize the client - use your access token here
$smartsheet_client = Smartsheet::Client.new(token: '1234')
# The `client` variable now contains access to all of the APIs

today = (DateTime.now)
date_week_ago = (today - 7).to_time.utc.iso8601 


def get_events(params)
  result = $smartsheet_client.events.get(params: params)
  # pp result
  print_new_sheet_events(result[:data])

  more_events_available = result[:more_available]
  next_stream_position = result[:next_stream_position]
  get_next_stream_of_events(more_events_available, next_stream_position)
end 

# Subsequent calls require the streamPosition property
def get_next_stream_of_events(more_events_available, next_stream_position)
  params = {
    stream_position: next_stream_position,
    max_count: 1
  }

  if more_events_available 
    get_events(params);
  end
end 

# This example is looking specifically for new sheet events
def print_new_sheet_events(data)
  data.each do |value|
    # Find all created sheets
    if value[:object_type] == "SHEET" && value[:action] == "CREATE"
        pp value
    end    
  end
end 


begin
  params = {
    since: date_week_ago,
    max_count: 1
  }

  # The first call to the events reporting API
  # requires the since query parameter.
  # If you pass in an UNIX epoch date, numericDates must be true
  get_events(params)

rescue Smartsheet::ApiError => e
  puts "Error Code: #{e.error_code}"
  puts "Message: #{e.message}"
  puts "Ref Id: #{e.ref_id}"
end

Example response

{
    "nextStreamPosition": "XyzAb1234cdefghijklmnofpq",
    "moreAvailable": "false",
    "data": [{
        "eventId" : "4b12345abc444def333g149he2b15b3j",
        "objectType" : "SHEET",
        "action" : "LOAD",
        "objectId" : 345678901234,
        "eventTimestamp" : 2019-04-29T08:28:33Z,
        "userId" : 123457654321,
        "requestUserId" : 133445566778,
        "source" : "WEB_APP",
        "additionalDetails" : { }
    }]
}

GET /events

Gets events that are occurring in your Smartsheet organization account. Examples of events are creation, update, load, and delete of sheets, reports, dashboards, attachments, users, etc.

Each event type has a distinct combination of objectType and action. Many event types have additional information returned under an additionalDetails object. See the Event Reporting reference documentation for a complete list of all currently supported events, including their respective objectType, action, and additionalDetails properties.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
	Accept-Encoding -- Strongly recommended to make sure payload is compressed. Must be set to one of the following values: deflate gzip
Parameters	since: Starting time for events to return. Intended for use only at client startup or recovery. This is intended for backfilling data and not for fine-grained date-based queries. Therefore, resolution is limited to the nearest hour. Interpreted as ISO-8601 format, unless numericDates is specified (see details about numericDates below) You must pass in a value for either since or streamPosition and never both.
	streamPosition: Indicates next set of events to return. Use value of nextStreamPosition returned from the previous call. You must pass in a value for either since or streamPosition and never both.
	maxCount (optional): Maximum number of events to return as response to this call. Must be between 1 through 10,000 (inclusive). Defaults to 1,000 if not specified.
	numericDates (optional): If true, dates are accepted and returned in Unix epoch time (milliseconds since midnight on January 1, 1970 in UTC time). Default is false, which means ISO-8601 format.
Returns	StreamResult object, populated according to the specified parameters
Access Scope	READ_EVENTS

Webhooks

Intro to Webhooks

Webhooks provide a way for Smartsheet to automatically notify your external application or service when certain events occur in Smartsheet. Webhooks offer a more efficient alternative to using the API to periodically poll for changes.

At a high-level, it works like this:

1. Your application subscribes to callbacks.
   First, subscribe to event notifications (callbacks) by creating one or more webhooks. You can create a webhook manually via the API or have your application create a webhook dynamically. Each webhook must specify:
   • Which Smartsheet object to monitor for events
   • Which events in that object should trigger a callback
   • The HTTPS URL (that is, "callback URL") where Smartsheet should send callbacks when any of the specified events occur within the scope of the specified Smartsheet object. (NOTE: Smartsheet webhooks do not support callbacks to servers using self-signed certificates)
   
   Webhook examples in plain English:
   • "When any changes occur in Sheet_A, send a callback to https://www.myapp.com/abc"
   • "When a new row is added to Sheet_B, send a callback to https://www.myapp.com/def"
   • "When a cell value is changed in Sheet_C, send a callback to https://www.myapp.com/ghi"
   
   
2. When any of the specified events occur within an object that is being monitored by a webhook, Smartsheet sends an HTTP POST (that is, "callback") to the callback URL that is associated with the webhook.
   
   • NOTE: The callback payload is a "skinny" payload -- it indicates which objects changed and the type of events that occurred, but does not contain any data from the objects themselves.
   
   
3. Your application receives, acknowledges, and processes callbacks.
   Your application receives the HTTP POST, acknowledges the callback by responding with HTTP status 200, and processes the callback. Because the callbacks are "skinny", make one or more requests to the Smartsheet API to retrieve the actual data associated with the change.

Webhook Management

Webhooks are created and managed by using the Smartsheet API. See Webhooks API Reference for details about the related API operations.

Webhook Ownership & Access

Webhooks can be created and managed via Direct API Access or by a third-party app.

A webhook that is created via Direct API Access:

• is owned by the user who created it
• can be managed only by the user who created it
• is not affected if the access token that was used to create it is revoked, as long as the user remains active

A webhook that is created by a third-party app:

• is owned by the user who authorized the third-party app (and is associated with the third-party app)
• can be managed by the third-party app (as long as it maintains authorization) or by the user who owns it
• is permanently disabled if the third-party app's permissions are revoked

Webhook Scope & Events

A webhook monitors the specified scope for the specified events.

A Webhook object's scope attribute indicates the scope of the subscription. It is specified when creating a webhook, and cannot subsequently be changed.

• Currently, sheet is the only supported value for the scope attribute.

A Webhook object's event attribute indicates the set of events that a webhook is subscribed to (that is, which events trigger a callback).

• Events are represented as a dot-separated string in the format "object.event", where an asterisk (*) can be used to represent "all objects" or "all events".
• Currently, *.* is the only supported value for the events attribute. This indicates a subscription to all objects in the scope, and all events for those objects.

Example

Consider a Webhook object with the following attribute values:

• scopeObjectId = 12345678901234
• scope = "sheet"
• events = "*.*"

This webhook monitors the specified sheet (id: 12345678901234) for all types of events. For example, if a row is added to the sheet, cell values are updated in the sheet, a column is deleted from the sheet, etc., a callback is sent to the webhook's callbackUrl.

Creating a Webhook

An API client can create a webhook by using the Create Webhook operation. A newly created webhook is disabled by default. After successfully creating a webhook, the API client must subsequently initiate and complete the verification process before the webhook is enabled. The following diagram illustrates the process of creating and enabling a webhook.

Step-by-Step:

The process occurs synchronously:

1. API client submits a Create Webhook request.

2. Smartsheet creates the webhook, but does not initially enable the webhook (enabled: false and status: "NEW_NOT_VERIFIED").

3. To initiate the verification process, the API client submits an Update Webhook request to specify enabled: true. (NOTE: The API client does not receive a response to this request until the verification process (steps 4 and 5) has completed.)

4. When Smartsheet receives the request to enable the webhook, it sends a verification request to the subscriber (that is, to the callbackUrl that the API client specified in the Create Webhook request). The request specifies a unique random value in the Smartsheet-Hook-Challenge header and contains only challenge and webhookId in the request body. The challenge value is a repeat of the header value for API clients that don't interpret header values.

5. The subscriber responds to the verification request by echoing back the same unique random value in the Smartsheet-Hook-Response header of the response. For API clients that don't interpret header values, you can also send a JSON body with a smartsheetHookResponse attribute and the same value that would have been in the header.

6. Once the subscriber has successfully acknowledged the verification request, Smartsheet enables the webhook and responds to the API client's Update Webhook request to confirm that the webhook has been enabled (enabled: true and status: "ENABLED").

Webhook Verification

Verification request (from Smartsheet):

POST [callbackUrl]
Smartsheet-Hook-Challenge: d78dd1d3-01ce-4481-81de-92b4f3aa5ab1 
{ 
  "challenge": "d78dd1d3-01ce-4481-81de-92b4f3aa5ab1",
  "webhookId": 2674017481058180
}

Verification response (by subscriber):

HTTP status: 200 OK
Smartsheet-Hook-Response: d78dd1d3-01ce-4481-81de-92b4f3aa5ab1 
{
  "smartsheetHookResponse": "d78dd1d3-01ce-4481-81de-92b4f3aa5ab1"
}

When an API client attempts to enable a webhook, Smartsheet sends a verification request to the webhook's callbackUrl to verify that the subscriber expects and is able to successfully receive callbacks. The request specifies a unique random value in the Smartsheet-Hook-Challenge header and contains a JSON object in the request body with only challenge and webhookId attributes in the request body. The challenge attribute is a repeat of the header value for API clients that don't interpret header values.

• To verify the webhook, the subscriber's response to the verification request must return a 200 HTTP status code and must echo back the same unique random value in the Smartsheet-Hook-Response header of the response or with a JSON smartsheetHookResponse attribute. Once Smartsheet receives this verification response, the webhook is enabled (enabled: true and status: "ENABLED").

• If the subscriber does not successfully respond to the verification request, the webhook remains disabled (enabled: false and status: "DISABLED_VERIFICATION_FAILED").

When a webhook is initially created through the API, the response contains the webhook's Id. If you wish to guarantee that your server only receives callbacks for webhooks that you created, you can check the verification request's webhookId attribute against your list of created webhook Ids. If the Id is not in the list, return a response with a non-200 status code (for example, 403 Forbidden), and the webhook that initiated the verification request is disabled as described above.

Webhook Status

A Webhook object's enabled attribute indicates whether a webhook is enabled or disabled, while the status attribute describes the reason that the webhook is enabled or disabled.

The following table lists all possible combinations of enabled and status attribute values.

Webhook.enabled	Webhook.status	Meaning	Notes
false	DISABLED_ADMINISTRATIVE	Webhook has been disabled by Smartsheet support.	A webhook in this state can only be re-enabled by Smartsheet (contact api@smartsheet.com). Attempting to re-enable a webhook in this state results in error code 1154.
false	DISABLED_APP_REVOKED	Webhook has been disabled because the third-party app associated with the webhook has had its access revoked.	This is a terminal state (that is, webhook in this state cannot be re-enabled, and attempts to do so result in error code 1153). If the third-party app's access is subsequently restored, it must create new webhooks.
false	DISABLED_BY_OWNER	Webhook has been disabled by the owner.	Owner can re-enable the webhook by using the Update Webhook operation to set enabled to true. Once the subscriber successfully acknowledges the verification request, the webhook is enabled.
false	DISABLED_CALLBACK_FAILED	Webhook has been disabled because callback was not successfully delivered to the callback URL.	Owner can re-enable the webhook by using the Update Webhook operation to set enabled to true. Once the subscriber successfully acknowledges the verification request, the webhook is enabled.
false	DISABLED_SCOPE_INACCESSIBLE	Webhook has been disabled because its owner lost access to the corresponding data in Smartsheet (either because the object was deleted or sharing permissions were revoked).	Webhook is automatically re-enabled if access to data is restored (for example, if deleted object is restored or sharing permissions are restored).
false	DISABLED_VERIFICATION_FAILED	Webhook verification has failed.	Owner can re-enable the webhook by using the Update Webhook operation to set enabled to true. Once the subscriber successfully acknowledges the verification request, the webhook is enabled.
true	ENABLED	Webhook is active.
false	NEW_NOT_VERIFIED	Webhook has been created but is not enabled because it has not yet been verified.	Owner can re-enable the webhook by using the Update Webhook operation to set enabled to true. Once the subscriber successfully acknowledges the verification request, the webhook is enabled.

Webhook Callbacks

A callback is the notification that Smartsheet sends to a webhook's callbackUrl. There are two types of callbacks:

• Event callback: Alerts the subscriber when the specified events have occurred in Smartsheet. This is the most common type of callback.

• Status Change callback: Alerts the subscriber that a webhook has been automatically disabled due to loss of access or automatically re-enabled due to restoration of access.

A Subscriber has the ability to verify the integrity of a callback payload (that is, ensure that the message was not tampered with en route) and authenticate the identity of its sender (that is, ensure that the callback did indeed originate from Smartsheet). For more information, see Authenticating Callbacks.

NOTES:

• Smartsheet webhooks do not support callbacks to servers using self-signed certificates. The callback server must be using a signed certificate from a certificate authority.
• The callbackURL cannot be a private IP address.
• The callbackURL must use one of the following ports: 443 (default for HTTPS), 8000, 8008, 8080, or 8443.

Event Callbacks

Example: event callback (row created)

{
  "nonce": "4b2ed20d-6f00-4b0c-8fac-082182aa9aac",
  "timestamp": "2015-10-27T17:04:23.795+0000",
  "webhookId": 4503604829677444,
  "scope": "sheet",
  "scopeObjectId": 4509506114742148,
  "events": [
    {
      "objectType": "sheet",
      "eventType": "updated",
      "id": 4509506114742148,
      "userId": 9007194052434043,
      "timestamp": "2015-10-27T17:03:15.000+0000"
    },
    {
      "objectType": "row",
      "eventType": "created",
      "id": 7129509179746180,
      "userId": 9007194052434043,
      "timestamp": "2015-10-27T17:03:15.000+0000"
    }
  ]
}

Smartsheet sends an event callback to notify the subscriber when the specified events occur in Smartsheet.

Callback Acknowledgement

The subscriber must respond to an event callback with a 200 HTTP status code to acknowledge that the callback was received.

Retry Logic

If the subscriber fails to respond with a 200 status, depending on the response, Smartsheet may retry delivery up to 14 times. (The first 7 retry attempts occur with a frequency that's determined using exponential backoff; thereafter, retry attempts occur once every three hours until all retries have been exhausted.)

Subscriber response	Is retried?
HTTP 201 through 299	No
HTTP 309 through 399	No
HTTP 400 through 499 (except 410)	Yes
HTTP 410	No
HTTP 500 through 599	Yes
Any other HTTP status	No
Request timeout	Yes

If the response is not retriable or retry attempts have been exhausted, the webhook is disabled (enabled: false and status: "DISABLED_CALLBACK_FAILED"). A webhook in this state can be re-enabled if the subscriber completes the verification process. (See Webhook Status for details.)

Status Change Callbacks

Status change callback (access lost):

{
  "nonce" : "20d4d741-6224-446f-b9c4-bf7802326192",
  "timestamp" : "2015-10-27T14:48:40.214+0000",
  "webhookId": 2674017481058180,
  "scope" : "sheet",
  "scopeObjectId" : 3407658024757124,
  "newWebhookStatus" : "DISABLED_SCOPE_INACCESSIBLE"
}

Status change callback (access restored):

{
  "nonce" : "20d4d741-6224-446f-b9c4-bf7802326192",
  "timestamp" : "2015-10-27T14:48:40.214+0000",
  "webhookId": 2674017481058180,
  "scope" : "sheet",
  "scopeObjectId" : 3407658024757124,
  "newWebhookStatus" : "ENABLED"
}

If a webhook's owner loses access to the object that a webhook is monitoring (either because the object was deleted or the webhook owner's access to the object was revoked in Smartsheet), Smartsheet automatically disables the webhook and sends a status change callback to alert the subscriber of this change in status. The newWebhookStatus attribute indicates that the webhook is now disabled (because the scope is inaccessible).

If the webhook owner's access to the object is subsequently restored, Smartsheet automatically re-enables the webhook and sends a status change callback to alert the subscriber of this change in status. The newWebhookStatus attribute indicates that the webhook is now enabled.

Authenticating Callbacks (optional)

Calculating an HMAC

# See programming language tabs for language-specific examples.

private static final String HMAC_SHA256_ALGORITHM="HmacSHA256";
private static final int HMAC_RADIX=16;

private String calculateHmac(String sharedSecret, String callbackBody)throws GeneralSecurityException{
  Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM));
  mac.init( new SecretKeySpec(sharedSecret.getBytes(), HMAC_SHA256_ALGORITHM));

  byte[]rawHmac = mac.doFinal(callbackBody.getBytes());
  return new BigInteger(1, rawHmac).toString(HMAC_RADIX);
}

A subscriber has the ability to verify the integrity of a callback payload (that is, ensure that the message was not tampered with en route) and authenticate the identity of its sender (that is, ensure that the callback did indeed originate from Smartsheet).

When you create a new webhook, it is assigned a randomly generated sharedSecret value. The shared secret is used by Smartsheet to sign callback payloads, and should not be shared with any third parties.

To authenticate a callback request:

1. Calculate the HMAC of the webhook's sharedSecret and the request body. This must be done using the SHA-256 cryptographic hash algorithm.

2. Format the calculated value as a string in base 16.

3. Compare your result with the value of the Smartsheet-Hmac-SHA256 header of the request.

If the values match, you can be sure the request originated from Smartsheet and that the data has not been tampered with.

Preventing Infinite Loops

Example request: Smartsheet-Change-Agent header

smartsheet_client.with_change_agent('MyChangeAgent')

# Specify updated cell values
body = {
  id: 4293147074291588,   # row Id
  cells: [
    column_id: 7036894123976580,
    value: 'new value'
  ]
}

# Update row
response = smartsheet.sheets.rows.update(
  sheet_id: 2068827774183300,
  body: body,
  header_overrides: {'Smartsheet-Change-Agent': 'MyChangeAgent'}
)

It's possible that an application which subscribes to callbacks (using webhooks) might react to those callbacks by using the API to make additional changes in Smartsheet. But, consider the following scenario:

1. App1 creates a webhook to monitor Sheet-A for changes, specifying an App-1 URL as the callbackUrl for the webhook.

2. App-1 updates Sheet-A using the API.

3. Smartsheet detects that Sheet-A has changed and sends a callback to App-1 (as the webhook specified).

4. App-1 processes the callback, and in the course of doing so, updates Sheet-A again using the API.

5. Return to Step 3.

To protect against infinite loops like the one outlined above, Smartsheet introduced support for a new header that an API client can include with any API request that adds, updates, or deletes data in Smartsheet. Here's how it works:

• An API client includes the Smartsheet-Change-Agent header in any API request that adds, updates, or deletes data in Smartsheet.
  • The header value should be set to a string that the API client recognizes as identifying itself.
• If any event callbacks fire as a result of an API request that contains the Smartsheet-Change-Agent header, the value of the Smartsheet-Change-Agent header is included in the callback in the value of the changeAgent attribute.
• If a webhook subscriber receives a callback that contains the changeAgent attribute, it should evaluate the attribute value:
  • If the attribute value's comma-delimited list contains the subscriber API client's change agent value, this indicates that the change which triggered the callback was caused by the subscriber itself, and the subscriber can choose to ignore the callback, thus preventing an infinite loop.
  • Else, the change which triggered the callback was not caused by the subscriber itself, and if the subscriber is going to subsequently react to the callback by making a change in Smartsheet (via API request), the API client should append a comma and its own identifier to the original attribute value, and pass that value through using the Smartsheet-Change-Agent header of the API request. Doing so protects against cross-system infinite loops.

Webhook Errors

The following table specifies the recommended action for each Smartsheet-specific error code. Use this information to implement error handling logic according to the following guidelines:

• If the error code indicates a permanent error condition, do not retry the request.
• If the error code indicates a problem that can be fixed, do not retry the request until the problem has been fixed.
• If the error code indicates a problem that could be overcome by retrying the request after a period of time, retry the request using exponential backoff.

HTTP status code	Smartsheet errorCode	Smartsheet message	Recommended Action
400	1151	Scope '{0}', object id {1} was not found.	Do not retry without fixing the problem.
400	1152	Only URLs with a protocol of 'https' are supported for attribute '{0}'.	Do not retry without fixing the problem.
403	1153	This webhook cannot be enabled because access was revoked for the application that created it.	Do not retry.
403	1154	Please contact api@smartsheet.com in order to enable this webhook.	Do not retry.

Webhooks Reference

Webhooks provide a way for Smartsheet to automatically notify your external application or service when certain events occur in Smartsheet. Webhooks offer a more efficient alternative to using the API to periodically poll for changes.

For more information, see Intro to Webhooks.

Objects

Callback Object

scopeObjectId	number	Id of the object that corresponds to scope
webhookId	number	Id of the corresponding webhook
events	CallbackEvent[]	Array of CallbackEvent objects
newWebhookStatus	string	New status of the corresponding webhook Only returned for webhook status change callbacks (null for event callbacks).
nonce	string	Random value that is distinct for each callback
scope	string	Scope of the webhook. Currently, the only supported value is sheet.
timestamp	timestamp	Time that the callback was generated

CallbackEvent Object

id	number	Id of the object that corresponds to objectType. Omitted if objectType is cell.
columnId	number	Only present if objectType is cell. The Id of the column where the cell is located.
rowId	number	Only present if objectType is cell. The Id of the row where the cell is located.
userId	number	The user Id of the person who caused this event.
objectType	string	Type of object for which event occurred. One of the following values: attachment cell column comment discussion row sheet
changeAgent	string	A comma-delimited list of values that uniquely identify the agents responsible for making the changes that caused the callback to occur. Only present if the change agent included the Smartsheet-Change-Agent header in the API request that changed data in Smartsheet. For more information, see Preventing Infinite Loops.
eventType	string	Type of event that occurred. One of the following values: created, deleted, updated
timestamp	timestamp	Time that this event occurred. A callback may contain events with different timestamps, as multiple separate events may be aggregated into a single callback request.

SharedSecret Object

sharedSecret	string	New value for the shared secret

Webhook Object

id	number	Webhook Id
apiClientId	string	API client Id corresponding to third-party app that created the webhook. Read-only. Only present if webhook was created by third-party app.
scopeObjectId	number	Id of the object that is subscribed to. Specified when a webhook is created and cannot be changed.
apiClientName	string	API client name corresponding to third-party app that created the webhook. Read-only. Only present if webhook was created by third-party app.
callbackUrl	string	HTTPS URL where callbacks are sent. NOTES: Smartsheet webhooks do not support callbacks to servers using self-signed certificates. The callback server must be using a signed certificate from a certificate authority. The callbackURL must use one of the following ports: 443 (default for HTTPS), 8000, 8008, 8080, or 8443.
createdAt	timestamp	Time of creation. Read-only.
disabledDetails	string	Details about the reason the webhook was disabled. Read-only. Only present when enabled=false.
enabled	Boolean	Indicates whether the webhook is on (true) or off (false)
events	string[]	Array of the events that are subscribed to. Currently, must be an array of size 1 that contains the string value "*.*", which means "all objects" and "all events".
modifiedAt	timestamp	Time of last modification. Read-only.
name	string	Webhook name
scope	string	Scope of the subscription. Currently, the only supported value is sheet. Specified when a webhook is created and cannot be changed.
sharedSecret	string	Shared secret for this webhook, randomly generated by Smartsheet. Read-only. See Authenticating Callbacks for details about how this value can be used.
stats	WebhookStats	Useful statistics for this webhook. Only returned once this webhook has performed a callback attempt. Read-only.
status	string	Webhook status. Read-only. See Webhook Status for list of possible values.
version	number	Webhook version. Currently, the only supported value is 1. This attribute is intended to ensure backward compatibility as new webhook functionality is released. For example, a webhook with a version of 1 is guaranteed to always be sent callback objects that are compatible with the version 1 release of webhooks.

WebhookStats Object

lastCallbackAttempt	timestamp	When this webhook last made a callback attempt.
lastCallbackAttemptRetryCount	number	The number of retries the webhook had performed as of the last callback attempt.
lastSuccessfulCallback	timestamp	When this webhook last made a successful callback.

Create Webhook

Example request: create webhook

curl https://api.smartsheet.com/2.0/webhooks \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "name": "Webhook #4", "callbackUrl": "https://www.myApp.com/webhooks", "scope": "sheet", "scopeObjectId": 2258256056870788, "version": 1, "events": [ "*.*" ]}'

// Specify webhook details
var body = {
  name: "Webhook #4",
  callbackUrl: "https://www.myApp.com/webhooks",
  scope: "sheet",
  scopeObjectId: 3285357287499652,
  events: ["*.*"],
  version: 1,
};

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

// Create webhook
smartsheet.webhooks.createWebhook(options)
  .then(function(newWebhook) {
    console.log(newWebhook);
  })
  .catch(function(error) {
    console.log(error);
  });

// Webhook specification
Webhook webhook = new Webhook
{
  Name = "Webhook #4",
  CallbackUrl = "https://www.myApp.com/webhooks",
  Scope = "sheet",
  ScopeObjectId = 3285357287499652,
  Events = new string[] { "*.*" },
  Version = 1
};

// Create Webhook
Webhook newWebhook = smartsheet.WebhookResources.CreateWebhook(
  webhook
);

// Webhook specification
Webhook webhook = new Webhook();
webhook.setCallbackUrl("https://www.myApp.com/webhooks")
  .setScope("sheet")
  .setScopeObjectId(3285357287499652L)
  .setEvents(Arrays.asList("*.*"))
  .setVersion(1)
  .setName("Webhook #4");

// Create Webhook
Webhook newWebhook = smartsheet.webhookResources().createWebhook(
  webhook
);

Webhook = smartsheet_client.Webhooks.create_webhook(
  smartsheet.models.Webhook({
    'name': 'Webhook #4',
    'callbackUrl': 'https://www.myApp.com/webhooks',
    'scope': 'sheet',
    'scopeObjectId': 3285357287499652,
    'events': ['*.*'],
    'version': 1}))

# Webhook specification
body = {
  name: 'Webhook #4',
  callback_url: 'https://www.myApp.com/webhooks',
  scope: 'sheet',
  scope_object_id: 3285357287499652,
  events: [
    '*.*'
  ],
  version: 1
}

response = smartsheet.webhooks.create(
  body: body
)
new_webhook = response[:result]

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": 8444254503626628,
    "name": "Webhook #4",
    "scope": "sheet",
    "scopeObjectId": 3285357287499652,
    "events": [ "*.*" ],
    "callbackUrl": "http://www.myApp.com/webhooks",
    "sharedSecret": "3qo29mvjou6xt5fujukjtwzhj0",
    "enabled": false,
    "status": "NEW_NOT_VERIFIED",
    "version": 1,
    "createdAt": "2015-11-03T22:25:51Z",
    "modifiedAt": "2015-11-03T22:25:51Z"
  }
}

POST /webhooks

Creates a new webhook.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Webhook object, limited to the following attributes: callbackUrl (required) events (required) name (required) scope (required) scopeObjectId (required) version (required)
Returns	Result object, containing a Webhook object for the newly created webhook
Access Scope	ADMIN_WEBHOOKS

Delete Webhook

Example request: delete webhook

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

// Set options
var options = {
  webhookId: 401090454808452
};

// Delete webhook
smartsheet.webhooks.deleteWebhook(options)
  .then(function(results) {
    console.log(results);
  })
  .catch(function(error) {
    console.log(error);
  });

smartsheet.WebhookResources.DeleteWebhook(
  401090454808452     // long webhookId
);

smartsheet.webhookResources().deleteWebhook(
  401090454808452L     // long webhookId
);

smartsheet_client.Webhooks.delete_webhook(
  401090454808452)       # webhook_id

smartsheet.webhooks.delete(
  webhook_id: 2674017481058180
)

Example response

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

DELETE /webhooks/{webhookId}

Deletes the webhook specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Result object
Access Scope	ADMIN_WEBHOOKS

Get Webhook

Example request: get webhook

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

// Set options
var options = {
  webhookId: 401090454808452
};

// Get webhook
smartsheet.webhooks.getWebhook(options)
  .then(function(webhook) {
    console.log(webhook);
  })
  .catch(function(error) {
    console.log(error);
  });

Webhook webhook = smartsheet.WebhookResources.GetWebhook(
  401090454808452     // long webhookId
);

Webhook webhook = smartsheet.webhookResources().getWebhook(
  401090454808452L     // long webhookId
);

Webhook = smartsheet_client.Webhooks.get_webhook(
  401090454808452)       # webhook_id

Webhook = smartsheet.webhooks.get(
  webhook_id: 2674017481058180
)

Example response

{
    "id": 401090454808452,
    "name": "Webhook #5",
    "scope": "sheet",
    "scopeObjectId": 6761855684241284,
    "events": [ "*.*" ],
    "callbackUrl": "http://www.myApp.com/webhooks",
    "sharedSecret": "216ejjzdnq17mq1q8xs7d4hu8b",
    "enabled": false,
    "status": "NEW_NOT_VERIFIED",
    "version": 1,
    "createdAt": "2015-11-03T22:25:51Z",
    "modifiedAt": "2015-11-04T20:12:42Z" 
}

GET /webhooks/{webhookId}

Gets the webhook specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	Webhook object
Access Scope	ADMIN_WEBHOOKS

List Webhooks

Example request: list webhooks

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

// Set options
var options = {
  };

// List webhooks
smartsheet.webhooks.listWebhooks(options)
  .then(function(webhookList) {
    console.log(webhookList);
  })
  .catch(function(error) {
    console.log(error);
  });

// Omit pagination parameters
PaginatedResult<Webhook> webhooks = smartsheet.WebhookResources.ListWebhooks(
  null            // PaginationParameters
);

// Omit pagination parameters
PagedResult<Webhook> webhooks = smartsheet.webhookResources().listWebhooks(
  null            // PaginationParameters
);

IndexResult = smartsheet_client.Webhooks.list_webhooks(
  page_size=100,
  page=1,
  include_all=False)

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

Example response

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": 
    [{
      "id": 4503604829677444,
      "name": "Webhook #5",
      "scope": "sheet",
      "scopeObjectId": 6761855684241284,
      "events": [ "*.*" ],
      "callbackUrl": "http://www.myApp.com/webhooks",
      "sharedSecret": "216ejjzfoo17mq1q8xs7d4hu8b",
      "enabled": true,
      "status": "ENABLED",
      "version": 1,
      "createdAt": "2015-11-03T14:52:21Z",
      "modifiedAt": "2015-11-04T19:05:40Z"
    }]
}

GET /webhooks

Gets the list of all webhooks that the user owns (if a user-generated token was used to make the request) or the list of all webhooks associated with the third-party app (if a third-party app made the request). Items in the response are ordered by API cient name > webhook name > creation date.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns	IndexResult object containing an array of Webhook objects
Access Scope	ADMIN_WEBHOOKS

Reset Shared Secret

Example request: reset shared secret

curl https://api.smartsheet.com/2.0/webhooks/{webhookId}/resetsharedsecret \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST

// Get options
var options = {
  webhookId: 401090454808452
};

// Reset shared secret
smartsheet.webhooks.resetSharedSecret(options)
  .then(function(newSecret) {
    console.log(newSecret);
  })
  .catch(function(error) {
    console.log(error);
  });

WebhookSharedSecret newSecret = smartsheet.WebhookResources.ResetSharedSecret(
  401090454808452     // long webhookId
);

WebhookSharedSecret newSecret = smartsheet.webhookResources().ResetSharedSecret(
  401090454808452L     // long webhookId
);

Webhook = smartsheet_client.Webhooks.reset_shared_secret(
  401090454808452)       # webhook_id

response = smartsheet.webhooks.reset_shared_secret(
  webhook_id: 401090454808452
)
updated_secret = response[:result]

Example response

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": { "sharedSecret": "5nua69a5foo57qdr9barbcg8f3" }
}

POST /webhooks/{webhookId}/resetsharedsecret

Resets the shared secret for the specified webhook. For more information about how a shared secret is used, see Authenticating Callbacks.

This operation can be used to rotate an API client's webhooks' shared secrets at periodic intervals to provide additional security.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	The request body should be empty.
Returns	Result object containing the SharedSecret object
Access Scope	ADMIN_WEBHOOKS

Update Webhook

Example request: update webhook

curl https://api.smartsheet.com/2.0/webhooks/{webhookId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{ "enabled": true }'

// Specify changed values
var body = {
  enabled: true
};

// Set options
var options = {
  webhookId: 8444254503626628,
  body: body
};

// Update webhook
smartsheet.webhooks.updateWebhook(options)
  .then(function(updatedWebhook) {
    console.log(updatedWebhook);
  })
  .catch(function(error) {
    console.log(error);
  });

// Webhook specification
Webhook webhook = new Webhook
{
  Id = 8444254503626628,
  CallbackUrl = "https://www.myApp.com/webhooks",
  Version = 1,
  Enabled = true
}

// Update Webhook
Webhook updatedWebhook = smartsheet.WebhookResources.UpdateWebhook(
  webhook
);

// Webhook specification
Webhook webhook = new Webhook();
webhook.setCallbackUrl("https://www.myApp.com/webhooks")
  .setVersion(1)
  .setEnabled(true)
  .setId(8444254503626628L);

// Update Webhook
Webhook updatedWebhook = smartsheet.webhookResources().updateWebhook(
  webhook
);

Webhook = smartsheet_client.Webhooks.update_webhook(
  8444254503626628,       # webhook_id
  ss_client.models.Webhook({
    'enabled': True}))

# Webhook specification
body = {
  name: 'Webhook #4',
  callback_url: 'https://www.myApp.com/webhooks/nouveau',
  events: [
    '*.*'
  ],
  enabled: true,
  version: 1
}

# Update Webhook
response = smartsheet.webhooks.update(
  webhook_id: 8444254503626628,
  body: body
)
updated_webhook = response[:result]

Example response

{
  "message": "SUCCESS",    
  "resultCode": 0,
  "result": {
    "id": 8444254503626628,
    "name": "Webhook #4",
    "scope": "sheet",
    "scopeObjectId": 2258256056870788,
      "events": [
        "*.*"
    ],
    "callbackUrl": "http://www.myApp.com/webhooks",
    "sharedSecret": "3qo29mvjou6xt5fujukjtwzhj0",
    "enabled": true,
    "status": "ENABLED",
    "version": 1,
    "createdAt": "2015-11-03T14:52:21Z",
    "modifiedAt": "2015-11-04T19:05:40Z"
  }
}

PUT /webhooks/{webhookId}

Updates the webhook specified in the URL.

Headers	Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json
Request Body	Webhook object, limited to the following attributes: callbackUrl (optional) enabled (optional) events (optional) name (optional) version (optional)
Returns	Result object containing the Webhook object for the updated webhook
Access Scope	ADMIN_WEBHOOKS