Smartsheet API 2.0
Updated 2021-04-06
Overview
To see Smartsheet’s current developer documentation, go to and bookmark Smartsheet API Reference, which now uses OpenAPI for API definitions and object modeling. For feedback, use Smartsheet Community for API Developers.
Introduction
Click the corresponding tab above to see sample code in the language of your choice. For more detail, see SDKs and Sample Code)
# The cURL code samples included in this API documentation demonstrate
# how to execute operations using the command line data transfer
# tool cURL: https://curl.haxx.se/.
// The Node.js code samples included in this API documentation demonstrate
// how to execute operations using the Smartsheet JavaScript
// SDK: https://github.com/smartsheet-platform/smartsheet-javascript-sdk.
// The C# code samples included in this API documentation demonstrate
// how to execute operations using the Smartsheet
// C# SDK: https://github.com/smartsheet-platform/smartsheet-csharp-sdk.
// The Java code samples included in this API documentation demonstrate
// how to execute operations using the Smartsheet
// Java SDK: https://github.com/smartsheet-platform/smartsheet-java-sdk.
# The Python code samples included in this API documentation demonstrate
# how to execute operations using the Smartsheet Python SDK:
# https://github.com/smartsheet-platform/smartsheet-python-sdk.
# The Ruby code samples included in this API documentation demonstrate
# how to execute operations using the Smartsheet
# Ruby SDK: https://github.com/smartsheet-platform/smartsheet-ruby-sdk.
Smartsheet API 2.0 allows you to programmatically access and manage your organization's Smartsheet data and account information. The API allows you to do the following:
- Read and update sheets
- Manage folders and workspaces
- Administer user accounts and organization account
You can view code examples in the programming language of your choice by clicking the corresponding tab in the dark-blue area in the rightmost pane. Each tab corresponds to a Software Development Kit (SDK) that Smartsheet provides to make working in that programming language easier. See SDKs and Sample Code.
How Do I Start?
This documentation provides two Getting Started tutorials that walk you through making your first API call and interpreting the response to a GET /sheet
request. You may also want to bookmark or note the following resources:
- Smartsheet Developer Portal: If registering, use a different email address from your paid Smartsheet account so you can test the API and make API calls
- Developer Newsletter (subscribe while at the Developer Portal using the "Get Developer Updates" form)
- StackOverflow using the "smartsheet-api" tag
- Contact us at help.smartsheet.com/contact
- 10000ft API documentation
- Review the Developer Program Agreement
HTTP and REST
RESTful Architecture
The REST URL structure follows typical resource-oriented conventions.
To get a list of sheets, use the following:
GET https://api.smartsheet.com/2.0/sheets
This returns a list of Sheet objects, where each sheet has an id attribute.
To get details on the sheet with id 123456, use the following:
GET https://api.smartsheet.com/2.0/sheets/123456
This Id pattern is repeated throughout the API. Columns, rows, cells, comments, attachments, or any other data element have a unique Id.
If you don't want to make raw HTTP calls, Smartsheet also has several Software Development Kits (SDKs) that provide a higher level interface for popular programming languages. For more information, see SDKs and Sample Code.
HTTP Verbs
Call the API using the following standard HTTP methods:
- GET (to retrieve an object or multiple objects in a specific category)
- POST (to create)
- PUT (to modify)
- DELETE
HTTP Status Codes
Smartsheet uses a combination of HTTP status codes and custom error codes with a descriptive message in JSON-formatted Error objects to give you a more complete picture of what has happened with your request.
HTTP status code |
Meaning | To Retry or Not to Retry? |
---|---|---|
2xx | Request was successful. Example: 200 Success |
-- |
4xx | A problem with request prevented it from executing successfully. | Never automatically retry the request. If the error code indicates a problem that can be fixed, fix the problem and retry the request. |
5xx | The request was properly formatted, but the operation failed on Smartsheet's end. | In some scenarios, requests should be automatically retried using exponential backoff. |
For example, doing a GET
on a non-existent sheet at https://api.smartsheet.com/2.0/sheets/123456
results in an HTTP status code of 404, indicating the resource was not found.
{ "errorCode": 1006, "message": "Not Found" }
Some errors may contain a detail attribute set to an object with additional error details that may be useful in programmatically handling the error. If so, it is noted in the specific API operation for which the error may occur.
HTTP Headers
Unless otherwise specified, all API endpoints expect request body data to be in JSON, and the response body data is returned as JSON.
The following HTTP request headers may be required, depending on the operation and endpoint being invoked:
Header | Definition | Example |
---|---|---|
Authorization | Required for all endpoints, except for POST /token . The access token. |
Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | Required for POST and PUT requests. Defines the structure for the response. | application/json |
Assume-User | Optional. Allows an admin to act on behalf of, or impersonate, the user to make API calls. The email address used to identify the user must be URI-encoded. | jane.doe%40smartsheet.com |
Query Strings
Example request: list sheets with query strings
curl https://api.smartsheet.com/2.0/sheets?include=attachments,source&includeAll=true \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
queryParameters: {
include: "attachments",
include: "source",
includeAll: true
}
};
// List sheets
smartsheet.sheets.listSheets(options)
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
PaginatedResult<Sheet> sheets = smartsheet.SheetResources.ListSheets(
new SheetInclusion[] { SheetInclusion.SOURCE },
new PaginationParameters(
true, // includeAll
null, // int pageSize
null) // int page
);
// Specify pagination parameter 'includeAll'
PaginationParameters page_params = new PaginationParameters()
.setIncludeAll(true);
// Specify `include` parameters
EnumSet include_params = EnumSet.of(SourceInclusion.SOURCE);
// List Sheets with pagination and include parameters
PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(include_params, page_params, null);
response = smartsheet_client.Sheets.list_sheets(include="attachments,source", include_all=True)
sheets = response.data
response = smartsheet.sheets.list(params: {include:"attachments,source", includeAll:true })
sheets = response
Many API calls can be modified by including one or more of these common query strings:
Query Parameter | Type | Description | More Info |
---|---|---|---|
allowPartialSuccess | Boolean | If true, allows bulk operations to process even if one or more operations are invalid for some reason, for example, allowPartialSuccess=true. | Bulk Operations |
include or exclude | String | When applicable for a specific object, various include or exclude parameters are available, for example, include=format. | Object reference or Formatting |
includeAll | Boolean | If true, includes all results, for example, includeAll=true. | Paging |
numericDates | Boolean | If true, allows you to input or receive dates in numeric format, for example, numericDates=true. | Dates and Times |
page | String | Specifies which page to return, for example, page=4. | Paging |
pageSize | Number | Specifies the maximum number of items to return per page, for example, pageSize=25. | Paging |
Authentication and Access Tokens
Example request: authentication and access tokens
curl https://api.smartsheet.com/2.0/users/me \
`-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set the access token
var client = require('smartsheet');
var smartsheet = client.createClient({accessToken:'ll352u9jujauoqz4gstvsae05'});
// Get current user
smartsheet.users.getCurrentUser()
.then(function(userProfile) {
console.log(userProfile);
})
.catch(function(error) {
console.log(error);
});
// Set the access token
String accessToken = "ll352u9jujauoqz4gstvsae05";
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(accessToken).Build();
// Get current user
UserProfile userProfile = smartsheet.UserResources.GetCurrentUser();
// Set the access token
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken("ll352u9jujauoqz4gstvsae05").build();
// Get current user
UserProfile userProfile = smartsheet.userResources().getCurrentUser();
# Create base client object and set the access token
smartsheet_client = smartsheet.Smartsheet('ll352u9jujauoqz4gstvsae05')
# Get current user
user_profile = smartsheet_client.Users.get_current_user()
require 'smartsheet'
# Add your token to the config.json file
{
"token": "ll352u9jujauoqz4gstvsae05",
"sheet_id": "5091283781476228"
}
Example response
{
"email": "john.doe@smartsheet.com",
"firstName": "John",
"lastName": "Doe",
"id": 48569348493401200
}
The Smartsheet API uses OAuth 2.0 for authentication and authorization. An HTTP header containing an access token is required to authenticate each request.
- To familiarize yourself with the API, you can generate a raw token. See Raw Token Requests.
- For additional security and as a recommended best practice, you should build an integration using OAuth 2.0. During the OAuth process, you will generate several API keys and, ultimately, each user will generate a unique access token.
Raw Token Requests
If you want to get started quickly, or are developing a standalone application that can run with your credentials, follow these instructions:
- Click the "Account" button in the upper-right corner of the Smartsheet screen, and then click "Personal Settings".
- Click the "API Access" tab.
- Click the "Generate new access token" button to obtain an access token.
The access token must be sent with every API call in an HTTP authorization header (except for the requests to Get Access Token or Refresh Access Token). Once you have an access token, include it in the Authorization header for every request you make:
Authorization: Bearer ll352u9jujauoqz4gstvsae05
The header name is Authorization and the value of the header is Bearer ll352u9jujauoqz4gstvsae05. Since the access token is being transmitted in clear text, all API calls are done over HTTPS.
Adding Security by Using OAuth
If your application requires users to be able to login with their own account, you must implement the full OAuth flow.
At a high level, this involves the following steps:
- Register as a Developer with Smartsheet so you can get access to the Developer Tools menu.
- Register your app to get both a clientId and client secret, which you'll need to store securely. Some best practices suggestions for security are below.
- Go through the steps in the Third-party App Development section once you are ready to request authorization.
Security Best Practices
The following provides some best practices to consider when working with the Smartsheet API and any API keys, tokens, or other sensitive information.
Source Code and Version control
Never commit API keys to accessible version control systems like GitHub or BitBucket. Instead, you should:
- Use an app configuration tool suitable for deploying secrets to your app, or
- Use a config file outside of source control, or
- Use environment variables set outside of source control.
If you have mistakenly deployed API keys to a publicly accessible location such as GitHub, then you should immediately revoke those API keys, revise your application to use a preferred method of key deployment, and then generate new keys.
If you need to store API keys in a database, consider the following protections:
- Restrict access so API keys are only readable by the owner of the object
- Restrict read privileges to the database table
- Make sure your database or the disk the database is on is set to encrypt data at rest
API Key Management
If you've committed code to a repository before implementing these security best practices, here are some steps to resecure your API keys.
For raw tokens:
- Revoke token
- Create a new token
If using OAuth for an integration:
- Work through the steps for Third-party App Development to regenerate client secrets, auth codes, and tokens.
Dates and Times
The Smartsheet API returns all dates and times in the UTC time zone in ISO-8601 format, that is, YYYY-MM-DDTHH:MM:SSZ. If you are specifying a date and time, you should also send that information in ISO-8601 format. If a date/time needs to be displayed to an end-user in their local time zone, you must do the conversion using the user's time zone, which you can obtain by getting the current user.
You can optionally choose to receive and send dates/times in numeric format, as milliseconds since the UNIX epoch (midnight on January 1, 1970 in UTC time), using the query string parameter numericDates with a value of true. This query parameter works for any API request.
Filtering
You cannot create or update filters using the API; however, you can query which rows have been filtered out and you can get filter definitions.
For details, see Filters object.
Formulas
Formulas are processed per cell in the UI. Use the Cell object to manipulate formulas via the API.
For requests, use Update Rows to add or update the formula in a cell.
For response payloads, formulas (when present) are returned whenever the Cell object is returned, so for example, GET /sheets/(id) returns the Cell object for each cell and that object contains a formula value when the cell contains a formula.
Object Details vs List Summaries
Many of the List All commands, for example, GET /sheets
, return only an abbreviated object for each object returned. For full details, read a single item, such as GET /sheets/{sheetId}
. In many cases, you can refine the exact object properties to be returned by using include and exclude query parameters.
The JSON representation of the objects returned from the List All REST endpoints will only include a subset of the properties documented here. However, the objects returned from the Java and C# SDKs will represent the omitted properties with NULLs.
Sheets/Columns/Rows/Cells
Sheets are composed of rows, columns, and cells. A cell is identified by the Id of its row and column. The following table defines these terms and points you to places in this documentation where you can find more information:
UI Element | Description | More Info |
---|---|---|
sheet | A sheet can exist in a user's Home folder, in a folder, or in a workspace. It is comprised of columns, rows, and cells, and may optionally contain attachments or discussions. | Sheet object |
column | A Column object defines the type of the column, but does not actually contain cells. The Column Id identifies the cells in a row. | Column object, Column types |
row | A row is a component of a sheet or report. Each row is composed of a collection of cells, and may optionally contain attachments or discussions. | Row object |
cell | A cell is a location within a sheet that may contain a value. A collection of cells comprises each row in a sheet. | Cell object, Cell reference |
Versioning and Changes
Smartsheet will add new functionality and bug fixes to the API over time. Make sure that your code can handle new JSON properties gracefully. Also, make sure your code does not depend on the order in which JSON objects are returned, unless it is explicitly stated in this documentation.
When there is new functionality that is not compatible with existing code, say in the case of a new concept, Smartsheet increments the level to indicate the new feature can be ignored until you are ready to implement the code to work with the new level.
See also: Working with Complex Objects: Multi-contact or Multi-picklist
Working with Complex Objects: Multi-contact or Multi-picklist
New column types, such as MULTI_CONTACT_LIST and MULTI_PICKLIST, offer more complex ways to work with columns. Smartsheet has provided a backwards compatible way for these payloads to work with your existing integrations while also giving you a way to query for their content.
With either column type, there are two ways of receiving the response:
- If you do nothing to your code, column types will display as TEXT_NUMBER
- If you use the level query parameter as detailed below, column types will display as MULTI_CONTACT_LIST or MULTI_PICKLIST and return a complex object (aka a non-primitive type)
Smartsheet uses two indicators to help you discover changes in the return data for your API calls:
- level: a query parameter that is incremented when a new feature or column type is added
- version: each element in the Columns array is set to one of the following values:
Text | Multi-contact | Multi-picklist |
---|---|---|
0 | 1 | 2 |
You must use the level query parameter, for example level=2, to return a complex object with the new column type. Without the query parameter, the response will be backwards-compatible, that is a string.
Use the highest possible level for each endpoint, as in the following table:
Endpoint category | Level |
---|---|
Dashboards (referred to as Sights in the API) | 4 |
Reports | 3 |
Sheets | 2 |
Working with Smartsheet Gov Accounts
Smartsheet Gov has "FedRAMP Authorized" status as part of Federal Risk and Authorization Management Program (FedRAMP). As an API developer working on a Smartsheet Gov account, you should be aware of the following differences from the standard API:
- The base URL for each API call is smartsheetgov.com instead of smartsheet.com. This documentation uses smartsheet.com in all examples.
- Smartsheetgov.com has a restriction on attachment types. Only the following attachment types are allowed: BOX_COM, FILE, GOOGLE_DRIVE, LINK, or ONEDRIVE.
If you use a Smartsheet SDK, you need to modify the standard config file to point to smartsheetgov.com. There are instructions specific to each SDK on how to modify the config file at the following locations:
Getting Started
Make Your First API Call
Before you write any code, try executing API requests using a tool like cURL or Postman. By taking your code out of the equation, you can isolate troubleshooting to the raw request and response.
You must use an access token. See instructions at Authentication and Access Tokens. In the examples below, replace this sample token, "ll352u9jujauoqz4gstvsae05", with your actual token value.
To get a list of all your sheets, try the following command:
curl -X GET -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" "https://api.smartsheet.com/2.0/sheets"
In Postman, the request looks like this:
The JSON result should look something like this (after formatting):
{ "pageNumber": 1, "pageSize": 100, "totalPages": 1, "totalCount": 2, "data": [{ "id": 6141831453927300, "name": "My first sheet", "accessLevel": "ADMIN", "permalink": "https://app.smartsheet.com/b/home?lx=8enlO7GkdYSz-cHHVus33A", "createdAt": "2016-01-28T22:02:35Z", "modifiedAt": "2016-08-09T17:50:06Z" }, { "id": 6141831453927300, "name": "Sheet shared to me", "accessLevel": "VIEWER", "permalink": "https://app.smartsheet.com/b/home?lx=8enlO7GkdYSz-cHHVus33A", "createdAt": "2016-01-28T22:02:35Z", "modifiedAt": "2016-08-09T17:50:06Z" } ] }
How to Read a Sheet Response
Many Smartsheet API operations handle sheets, rows, columns, and cells. Each is identified by an Id and it is important to understand the relationship between these objects. Typically you loop through the columns to determine the Id of the columns you are interested in. Then you loop through the rows and contained cells to find actual values. The annotated sample response below illustrates these concepts by calling a very simple sheet called "Employee Roster".
Before you begin, you should already have an access token, which you used in the exercise above. Use the same access token for this walkthrough.
Step 1: The first thing you must have is a sheetId. To find a sheetId through the UI, with the sheet open, click "Sheet Actions" in the left toolbar and select "Properties". NOTE: use List Sheets if you want to do this programmatically.
Step 2: Copy the sheetId into the API call, GET /sheets
, as below:
curl -X GET -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" "https://api.smartsheet.com/2.0/sheets/6141831453927300"
Step 3: The sample request and response are displayed below. NOTE: while JSON doesn't have a comment feature, this sample uses comments to help you identify the objects in the response.
{ "id": 6141831453927300, // This is the Id of the entire sheet "name": "My first sheet", "columns": [{ // Each Column object associates column // Id to title and defines the // column details "id": 2517104256673668, // Column Id identifies cells on a row "index": 0, "title": "Name", // This is the column name as seen // in the UI "type": "TEXT_NUMBER", "primary": true, "width": 150 }, { "id": 7020703884044164, "index": 1, "title": "EmployeeId", "type": "TEXT_NUMBER", "width": 150 } ], "rows": [{ // A Row object "id": 564480076736388, // Use the row Id to make updates "rowNumber": 1, "expanded": true, "createdAt": "2017-05-12T16:52:38Z", "modifiedAt": "2017-05-22T20:40:14Z", "cells": [{ // Each row contains an array of cells, // which have the actual content "columnId": 2517104256673668, // The column Id can be interpreted by // looking at the array of column // definitions above. That tells you // this is the "Name" column "value": "John Doe", "displayValue": "John Doe" }, { "columnId": 7020703884044164, "value": 12345, // Actual cell value "displayValue": "12,345" // How the cell value is displayed // in the UI } ]}, { "id": 5068079704106884, "rowNumber": 2, "siblingId": 564480076736388, "expanded": true, "createdAt": "2017-05-12T16:52:38Z", "modifiedAt": "2017-05-22T20:40:14Z", "cells": [{ "columnId": 2517104256673668, "value": "Jane Roe", "displayValue": "Jane Roe" }, { "columnId": 7020703884044164, "value": 67890, "displayValue": "67890" } ] } ] }
This core hierarchy of Sheet > Column > Row > Cell is essential to working with the Smartsheet API. As your user's sheets grow in complexity, the responses do too. This walkthrough has given you some navigational aid in finding the right value to plug into your API calls. Use the API Reference and the example language tabs to learn more.
SDKs and Sample Code
Install the SDK
# The cURL code samples included in this API documentation demonstrate
# how to execute operations using the command line data transfer
# tool cURL: https://curl.haxx.se/.
npm install smartsheet
// In the Visual Studio Package Manager Console
Install-Package smartsheet-csharp-sdk
// Add the SDK as a dependency in your project
<dependency>
<groupId>com.smartsheet</groupId>
<artifactId>smartsheet-sdk-java</artifactId>
<version>2.2.0</version>
</dependency>
$ pip install smartsheet-python-sdk
# Add this line to your application's Gemfile
gem 'smartsheet', '>= 1.0.0'
# And then execute
$ bundle
Load the client
# Click the corresponding language tab when using the SDK for that language.
// Initialize client SDK
var client = require('smartsheet');
var smartsheet = client.createClient({ accessToken: ll352u9jujauoqz4gstvsae05 });
using Smartsheet.Api;
using Smartsheet.Api.Models;
// Initialize client
String accessToken = "ll352u9jujauoqz4gstvsae05";
SmartsheetClient smartsheet = new SmartsheetBuilder()
.SetAccessToken(accessToken)
.Build();
import com.smartsheet.api.*;
import com.smartsheet.api.models.*;
import com.smartsheet.api.oauth.*;
// Initialize client
String accessToken = "ll352u9jujauoqz4gstvsae05";
Smartsheet smartsheet = new SmartsheetBuilder()
.setAccessToken(accessToken)
.build();
import smartsheet
# Initialize client
smartsheet_client = smartsheet.Smartsheet(access_token)
# Make sure we don't miss any errors
smartsheet_client.errors_as_exceptions(True)
require 'smartsheet'
require 'logger'
logger = Logger.new(STDOUT)
logger.level = Logger::INFO
# Initialize client
smartsheet = Smartsheet::Client.new(token: 'll352u9jujauoqz4gstvsae05', logger: logger)
# Example call
response = smartsheet.sheets.list
sheets = response[:data]
# Return is a Ruby Hash as below, though this document
# displays a JSON example to accommodate the multiple tabs
{
:id=>0123456789012345,
:name=>"Expense Report May 2017",
:access_level=>"VIEWER",
:permalink=>"https://app.company.com",
:created_at=>"2016-12-08T21:14:43Z",
:modified_at=>"2017-08-20T02:47:41Z"
}
Smartsheet has Software Development Kits (SDKs) providing a higher level interface for several languages.
Language | SDK | Sample application |
---|---|---|
C# | smartsheet-csharp-sdk | csharp-read-write-sheet |
Java | smartsheet-java-sdk | java-read-write-sheet |
Node.js | smartsheet-javascript-sdk | node-read-write-sheet |
Python | smartsheet-python-sdk | python-read-write-sheet |
Ruby | smartsheet-ruby-sdk | ruby-read-write-sheet |
In addition to the sample application provided for each SDK, you can always view code examples in this document by clicking the corresponding tab in the dark-blue area in the rightmost pane.
To use an SDK for development work, follow the instructions in the SDK readme to download and install the SDK. Then download the sample app and run it. Once you've run the sample application, you can clone it and use the structure it provides to start building your own applications.
Permission Levels
Access Levels
Sheets, templates, and workspaces have an accessLevel attribute that describes the current user's access level to that object. This corresponds directly to the sharing and access controls of Smartsheet that are available through the Smartsheet UI. The accessLevel attribute has one of the following values:
Value | Description |
---|---|
ADMIN | The user can edit and share the resource, and can alter the structure of the resource as well. |
EDITOR | The user can edit the resource, but cannot alter the structure of, delete, or share the resource. |
EDITOR_SHARE | The same as EDITOR, but with the ability to share the resource to other users. |
OWNER | The user has complete control over the resource. |
VIEWER | The user has read-only access to the resource. |
Assume User
Example: assume user
curl https://api.smartsheet.com/2.0/sheets \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Assume-User: jane.doe%40smartsheet.com" \
// Set options
var options = {
assumeUser: "jane.doe@smartsheet.com"
};
// List Sheets
smartsheet.sheets.listSheets(options)
.then(function(sheetList) {
console.log(sheetList);
})
.catch(function(error) {
console.log(error);
});
SmartsheetClient smartsheet = new SmartsheetBuilder()
.SetAccessToken(accessToken)
.SetAssumedUser("jane.doe@smartsheet.com")
.Build();
smartsheet.setAssumedUser("jane.doe@smartsheet.com");
smartsheet_client.assume_user("jane.doe@smartsheet.com")
smartsheet.sheets.list(
header_override: {:'Assume-User' => CGI::escape('jane.doe@smartsheet.com')}
)
Allows an admin to act on behalf of, or impersonate, the user to make API calls. You might do this to troubleshoot a user problem or cover for vacations and sick time. As with cURL, the email address used to identify the user must be URI-encoded.
An admin cannot impersonate another admin.
Third-party App Development
Apps connect to Smartsheet using OAuth 2.0 to authenticate and authorize users. If you are building an app, this documentation will walk you through the steps you need to authenticate your users. The Smartsheet SDKs contain APIs for OAuth 2.0.
First Steps
Before you can start using OAuth 2.0 with your app, Smartsheet needs the following information:
- You must register with Smartsheet to get a developer account*. The developer account gives you access to "Developer Tools", which is where you manage your app.
- In "Developer Tools", complete your developer profile. This profile is public and anyone can access it to learn about you and your apps.
- In "Developer Tools", register your app so Smartsheet can assign a client Id and a client secret to the app.
- Review the list of access scopes. You'll need to choose which ones your app needs to get to a user's Smartsheet data, and then ask the user to consent to that access.
After you've worked through these steps, you'll be ready to implement the OAuth Flow.
*Review the Developer Program Agreement.
Open Developer Tools
- Log in to Smartsheet with your developer account.
- Click the "Account" button in the upper-right corner of your Smartsheet screen, and then click "Developer Tools".
- Do one of the following:
- If you need to register an app, click "Create New App".
- If you need to manage an app, click "view/edit" for the app.
Register Your App Using Developer Tools
- Log in to Smartsheet with your developer account.
- Click the "Account" button in the upper-right corner of your Smartsheet screen, and then click "Developer Tools".
- In the "Create New App" form, provide the following information:
- Name: the name the user sees to identify your app
- Description: a brief description intended for the user
- URL: the URL to launch your app, or the landing page if not a web app
- Contact/support: support information for the user
- Redirect URL: also known as a callback URL. The URL within your application that will receive the OAuth 2.0 credentials
After you click "Save", Smartsheet assigns a client Id and secret to your app. Make a note of these Ids for the next steps; however, you can always look them up again in "Developer Tools".
Access Scopes
To access a user's Smartsheet data, your application must explicitly ask the user for permission. You do this by using access scopes, which enable your app to communicate to the user what type of operations it is performing. Access scopes do not override existing access-level restrictions. For example, having the access scope of WRITE_SHEETS does not allow your app to update a sheet on which the user has VIEWER access level.
The access scopes are as follows:
Access Scope | Description |
---|---|
ADMIN_SHEETS | Modify sheet structure, including column definition, publish state, etc. |
ADMIN_SIGHTS | Modify dashboards structure. |
ADMIN_USERS | Add and remove users from your Smartsheet organization account; create groups and manage membership. |
ADMIN_WEBHOOKS | Create, delete, and update webhooks; get all webhooks; reset shared secret. |
ADMIN_WORKSPACES | Create and manage workspaces and folders, including sharing. |
CREATE_SHEETS | Create new sheets. |
CREATE_SIGHTS | Create new dashboards. |
DELETE_SHEETS | Delete sheets. |
DELETE_SIGHTS | Delete dashboards. |
READ_CONTACTS | Retrieve contacts. |
READ_SHEETS | Read all sheet data, including attachments, discussions, and cell data. |
READ_SIGHTS | Read all dashboards data. |
READ_USERS | Retrieve users and groups for your Smartsheet organization account. |
SHARE_SHEETS | Share sheets, including sending sheets as attachments. |
SHARE_SIGHTS | Share dashboards. |
WRITE_SHEETS | Insert and modify sheet data, including attachments, discussions, and cell data. |
OAuth Flow
Your app must implement a 3-legged OAuth flow to retrieve an access token it can use to access Smartsheet data on behalf of an end user. The following diagram has an overview of the OAuth flow:
Request an Authorization Code
Request an authorization code:
curl 'https://app.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE' \
-X GET
const qs = require('querystring');
function authorizeURL(params) {
const authUrl = 'https://app.smartsheet.com/b/authorize';
return `${authUrl}?${qs.stringify(params)}`;
}
const authorizationUri = authorizeURL({
response_type: 'code',
client_id: '1samp48lel5for68you',
redirect_uri: 'http://localhost:3000/callback',
scope: 'CREATE_SHEETS WRITE_SHEETS',
});
// Initial page redirecting to Smartsheet
app.get('/auth', (req, res) => {
console.log(authorizationUri);
res.redirect(authorizationUri);
});
OAuthFlow oauth = new OAuthFlowBuilder()
.SetClientId("1samp48lel5for68you")
.SetClientSecret("sxouqll7zluvzmact3")
.SetRedirectURL("http://localhost:3000/callback")
.Build();
string url = oauth.NewAuthorizationURL
(
new Smartsheet.Api.OAuth.AccessScope[]
{
Smartsheet.Api.OAuth.AccessScope.READ_SHEETS,
Smartsheet.Api.OAuth.AccessScope.WRITE_SHEETS,
Smartsheet.Api.OAuth.AccessScope.SHARE_SHEETS,
Smartsheet.Api.OAuth.AccessScope.DELETE_SHEETS,
Smartsheet.Api.OAuth.AccessScope.CREATE_SHEETS,
Smartsheet.Api.OAuth.AccessScope.READ_USERS,
Smartsheet.Api.OAuth.AccessScope.ADMIN_USERS,
Smartsheet.Api.OAuth.AccessScope.ADMIN_SHEETS,
Smartsheet.Api.OAuth.AccessScope.ADMIN_WORKSPACES,
},
"key=Test"
);
// Take the user to the following URL
Debug.WriteLine(url);
// After the user accepts or declines the authorization they are taken to the redirect URL. The URL of the page
// the user is taken to can be used to generate an authorization RequestResult object.
string authorizationResponseURL = "http://localhost:3000/callback/?code=yn8kl1kvzzz31uj&expires_in=599997&state=key%3DTest";
// On this page pass in the full URL of the page to create an authorizationResult object
AuthorizationResult authResult = oauth.ExtractAuthorizationResult(authorizationResponseURL);
// [todo]
# [todo]
auth_request_url = client.token.build_authorization_url(
client_id: 'my-client-id',
scopes: ['CREATE_SHEETS', 'WRITE_SHEETS'])
Successful Response:
// The user sees your app's consent page
GET https://app.smartsheet.com/b/authorize
POST https://app.smartsheet.com/b/authorize
Initiates the process to get authorization from the user. Smartsheet will redirect this URL to display your app's consent page with an explanation of the data the app will need access to. This consent page is autogenerated by Smartsheet based on a combination of the information you registered for your app and the parameters you send with the request.
Value | Description |
---|---|
client_id | Required. The client Id you obtained when you registered your app. |
response_type | Required. Indicates whether the endpoint returns an authorization code. Must be set to "code". |
scope | Required. Space-delimited list of access scopes to which you are asking the user to grant access. NOTE: No access scopes are necessary if you simply need to validate that the user has a Smartsheet account. |
state | Optional. An arbitrary string of your choosing that is returned to your app; a successful roundtrip of this string helps ensure that your app initiated the request. |
You can view code examples by clicking the corresponding tab in the dark-blue area in the rightmost pane. The cURL example shows a GET
.
A correctly formatted Auth URL request looks like this: https://app.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE
At this point, the user can authorize your app to access their Smartsheet account, as in the following example:
After the user clicks "Allow" or "Deny", you'll receive a response from Smartsheet outlined in the next sections.
If the User Clicks Allow
Successful Response:
'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'
'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'
'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'
'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'
'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'
'http://localhost:3000/callback?code=sample6p9qisx6a&expires_in=599080&state=MY_STATE'
If the user clicks "Allow", Smartsheet redirects the user to the callback URL with the following parameters:
Value | Description |
---|---|
code | Authorization code required to obtain access token, such as 'sample6p9qisx6a'. |
expires_in | Number of milliseconds code is valid once issued; this is currently 599135 milliseconds, or approx. 10 minutes--you must obtain an access token within that time. |
state | The same value for state that you sent when you requested the authorization code. |
At this point, you should verify the state value matches what you sent to the user when you requested the authorization code. This helps you determine that the response came from the user and not a malicious script. If the values do not match, you should reject the response.
For other error conditions, see the list of OAuth Error Types.
If the User Clicks Deny
If the user clicks "Deny", Smartsheet redirects the user to the callback URL with the following parameters:
Value | Description |
---|---|
error | "access_denied". |
state | The same value for state that you sent when you requested the authorization code. |
For other error conditions, see the list of OAuth Error Types.
Request an Access Token
Request an access token:
// Sample 1: Use a hash
curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&hash={SHA_256(app_secret|code)}' \
-X POST
// Sample 2: Use plain text
curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&client_secret={app_secret}' \
-X POST
// Sample 1: Use a hash
// Create hash
var hash =
crypto.createHash('sha256')
.update('9samp7le3for71you' + '|' + 'sample6p9qisx6a')
// ('Your App Secret' + '|' + 'Received Authorization Code')
.digest('hex');
// Set options
var options = {
queryParameters: {
client_id: '1samp48lel5for68you', // Your App Client ID
code: 'sample6p9qisx6a', // Received Authorization Code
hash: hash
},
contentType: 'application/x-www-form-urlencoded'
};
// Get access token
smartsheet.tokens.getAccessToken(options)
.then(function(token) {
console.log(token);
})
.catch(function(error) {
console.log(error);
});
// Sample 2: Use plain text
// In progress
// Sample 1: Use a hash
// Get the token from the authorization result (see "Request an authorization code")
Token token = oauth.ObtainNewToken(
authResult // AuthorizationResult authResult
);
// Refresh an access token
Token tokenRefreshed = oauth.RefreshToken(token);
// Sample 2: Use plain text
// In progress
// [todo]
# [todo]
# Sample 1: Use a hash
hash = Digest::SHA256.hexdigest '9samp7le3for71you|sample6p9qisx6a'
# your_app_secret|your_code
smartsheet.token.get(
client_id: '1samp48lel5for68you',
code: 'sample6p9qisx6a',
hash: hash
)
# Sample 2: Use plain text
# In progress
Successful Response:
{
"token": {
"access_token": "ll352u9jujauoqz4gstvsae05",
"token_type": "bearer",
"refresh_token": "e9x352a9mp4151le2505",
"expires_in": 604799
}
}
Error Response:
{
"errorCode": "Smartsheet error number",
"error": "OAuth error type",
"error_description": "Error description"
}
POST /token
Once you’ve successfully obtained an authorization code, the next step is to exchange the code for an access token. (Remember, the authorization code expires after 599135 milliseconds.)
Value | Description |
---|---|
client_id | Required. The client Id you obtained when you registered your app. |
client_secret | Optional. Must use either this value or hash. Plain text method for sending this value. For example, client_secret={app_secret} . Encryption occurs at the HTTPS level. |
code | Required. Authorization code returned in the previous step. |
grant_type | Required. Must be set to "authorization_code". |
hash | Optional. Must use either this value or client_secret. SHA-256 hash of your app secret concatenated with a pipe and the authorization code. For example, hash={SHA_256(app_secret|code)} . |
If your request is successful, the response will contain a Token object. You can see an example of the Token object in the dark-blue area in the rightmost pane.
For possible error conditions, see the list of OAuth Error Types.
Refresh an Access Token
Refresh an access token:
Sample 1: Use a hash
curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=refresh_token&refresh_token={your_refresh_token}&client_id={your_client_id}&hash={SHA_256(app_secret|refresh_token)}' \
-X POST
Sample 2: Use plain text
curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=refresh_token&refresh_token={your_refresh_token}&client_id={your_client_id}&client_secret={app_secret}' \
-X POST
// Sample 1: Use a hash
// Create hash
var hash =
crypto.createHash('sha256')
.update('9samp7le3for71you' + '|' + 'sample6p9qisx6a')
// ('Your App Secret' + '|' + 'Your App Refresh Token')
.digest('hex');
// Set options
var options = {
queryParameters: {
client_id: '1samp48lel5for68you', // Your App Client ID
refresh_token: 'e9x352a9mp4151le2505',
hash: hash
},
contentType: 'application/x-www-form-urlencoded'
};
// Refresh access token
smartsheet.tokens.refreshAccessToken(options)
.then(function(updatedToken) {
console.log(updatedToken);
})
.catch(function(error) {
console.log(error);
});
// Sample 2: Use plain text
// In progress
// Sample 1: Use a hash
Token tokenRefreshed = oauth.RefreshToken(token);
// Sample 2: Use plain text
// In progress
// [todo]
# [todo]
# Sample 1: Use a hash
hash = Digest::SHA256.hexdigest '9samp7le3for71you|e9x352a9mp4151le2505'
# your_app_secret|refresh_token
smartsheet.token.refresh(
client_id: '1samp48lel5for68you',
refresh_token: 'e9x352a9mp4151le2505',
hash: hash
)
# Sample 2: Use plain text
# In progress
Successful Response:
{
"token": {
"access_token": "new52u9jujauoqz4gstvsae05",
"token_type": "bearer",
"refresh_token": "new352a9mp4151le2505",
"expires_in": 604799
}
}
POST /token
Access tokens expire after 604799 seconds, which is approx 7 days. Use the refresh token to obtain a new access token and a new refresh token. Once you obtain the new tokens, you must use them in place of the old ones, which are no longer valid.
Value | Description |
---|---|
client_id | Required. Client Id for your app. |
client_secret | Optional. Must use either this value or hash. Plain text method for sending this value. For example, client_secret={app_secret} . Encryption occurs at the HTTPS level. |
grant_type | Required. Must be set to refresh_token. |
hash | Optional. Must use either this value or client_secret. SHA-256 hash of your app secret concatenated with a pipe and the refresh token. For example, hash={SHA_256(app_secret|refresh_token)} . |
refresh_token | Required. refresh_token value that came with the access token. |
redirect_uri | Deprecated. If supplied, must match the redirect URI you registered for your app. |
If your request is successful, the response will contain a Token object. You can see an example of the Token object in the dark-blue area in the rightmost pane.
OAuth Error Types
Value | Description |
---|---|
invalid_client | The client information is invalid. Ensure your client id is correct. |
invalid_grant | The authorization code or refresh token is invalid or expired or the hash value does not match the app secret and/or code. |
invalid_request | The request parameters are invalid or missing. |
invalid_scope | One or more of the requested access scopes is invalid. Please check the list of access scopes. |
unsupported_grant_type | grant_type must equal authorization_code or refresh_token. |
unsupported_response_type | response_type must be set to code. |
Work at Scale
Bulk Operations
The Smartsheet API supports a number of bulk operations that can operate on multiple objects. Unlike single-object operations, bulk operations allow you to create, update, or delete multiple objects in a single request. For example, if you want to update 10 rows within a sheet, do so using a single Update Rows request, rather than executing 10 separate requests - one for each row.
Optional Bulk Operations
Several endpoints support optional bulk POST
operations which exist alongside the standard single-object POST
. For these endpoints, you may pass in either a single object or an array of objects.
Depending on what was passed in, the Result object returned contains either a single object or an array. An example optional bulk operation is POST /favorites: you can
pass in a single Favorite object to create a single favorite, or an array of Favorite objects to create multiple favorites in a single request. Endpoints which support bulk operations are
noted as such in the API reference documentation.
NOTE: Most POST
operations fail when attempting to create a single object which already exists (for example, favorites, shares, group members). However, for the corresponding bulk operations, these endpoints do not
return an error if one or more items in the array already exist. Existing items are simply ignored, and the Result object returned omits them.
Partial Success
In general, the default behavior for bulk operations is to fail outright if any of the objects in the request are invalid for some reason. If successful, Smartsheet creates/updates/deletes all objects in the request; if not, no objects are changed.
However, there are some operations that support partial success, which means the operation still succeeds even if one or more of the objects in the request fails for some reason (for example, an object is invalid). Here is another example: if you want to update more than one row, you send more than one row object in your request. If a row object is invalid, that row update will fail, but the other row updates will succeed. Partial success is not the default mode for an operation and you must explicitly enable it by using a query string parameter. This is noted in the documentation for operations that support partial success.
When partial success is enabled, and one or more of the objects in the request fail to be added/updated/deleted, a standard Result object is returned, but with a message of 'PARTIAL_SUCCESS' (instead of 'SUCCESS'), and a resultCode of 3. Additionally, the object contains a failedItems attribute -- an array of BulkItemFailure objects that contains an item for each object in the request that failed to be added/updated/deleted.
Paging
The Smartsheet API contains a number of index endpoints (typically denoted in the documentation with titles beginning with "Get All" or "List") which return arrays of objects.
Examples include GET
/users, /sheets, /sheets/{sheetId}/columns, and many others. These endpoints all support pagination, meaning
you can retrieve paged subsets of results, enabling you to process potentially large result sets in smaller chunks.
Paging Query String Parameters
Example request: list sheets with pagination query strings
curl https://api.smartsheet.com/2.0/sheets?include=attachments,source&includeAll=true \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
queryParameters: {
include: "attachments",
include: "source",
includeAll: true
}
};
// List sheets
smartsheet.sheets.listSheets(options)
.then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
PaginatedResult<Sheet> sheets = smartsheet.SheetResources.ListSheets(
new SheetInclusion[] { SheetInclusion.SOURCE },
new PaginationParameters(
true, // includeAll
null, // int pageSize
null) // int page
);
// Specify pagination parameter 'includeAll'
PaginationParameters page_params = new PaginationParameters()
.setIncludeAll(true);
// Specify `include` parameters
EnumSet include_params = EnumSet.of(SourceInclusion.SOURCE);
// List Sheets with pagination and include parameters
PagedResult<Sheet> sheets = smartsheet.sheetResources().listSheets(include_params, page_params, null);
response = smartsheet_client.Sheets.list_sheets(include="attachments,source", include_all=True)
sheets = response.data
response = smartsheet.sheets.list(params: {include:"attachments,source", includeAll:true })
sheets = response
Index endpoints all support pagination via the following optional query string parameters:
Value | Type | Description |
---|---|---|
includeAll | Boolean | If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified). |
page | number | Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
pageSize | number | The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. |
Paged Responses
Index endpoints all return paged responses via an IndexResult object, which provides paging metadata that can be used to navigate the full set of pages in the result set:
data | array | An array of objects representing the current page of data in the result set. |
pageNumber | number | The current page in the full result set that the data array represents. NOTE: when a page number greater than totalPages is requested, the last page is instead returned. |
pageSize | number | The number of items in a page. Omitted if there is no limit to page size (and hence, all results are included). Unless otherwise specified, this defaults to 100 for most endpoints. |
totalCount | number | The total number of items in the full result set. |
totalPages | number | The total number of pages in the full result set. |
Rate Limiting
Handle "Rate limit exceeded" Error
To prevent abuse and undue stress on the Smartsheet servers, the API has a rate limiting feature (sometimes called throttling) that restricts users to 300 requests per minute per access token. Certain resource intensive operations, such as attaching a file and getting cell history, count as 10 requests. Smartsheet reserves the right to enforce this limit depending on the load on our systems. If and when the limit is enforced, any requests that exceed this limit are rejected with an 429 HTTP status code, along with the following JSON response body:
{ "errorCode": 4003, "message": "Rate limit exceeded." }
Smartsheet recommends that you design your integration to gracefully handle this rate limit error. One way of doing that would be to have your integration sleep for 60 seconds when this error is encountered, and then subsequently retry the request. Alternatively, you might choose to implement exponential backoff (an error handling strategy whereby you periodically retry a failed request with progressively longer wait times between retries, until either the request succeeds or the certain number of retry attempts is reached).
Avoid Executing "Rapid Fire" Updates
If the only thing your integration does is execute an Update Rows request once every second for the same sheet, that would only amount to a total of 60 requests per minute -- well within rate limiting guidelines. However, updating the same object in such rapid succession could result in save errors that negatively impact both your integration as well as user experience within the Smartsheet app. To avoid this scenario, design your integration such that API requests are never executed with rapid-fire succession against the same Smartsheet object. For maximum efficiency, consider batching up changes and submitting them in a single request using a bulk operation (for example, Update Rows or Add Columns.
Execute Requests Serially
Executing multiple API requests in parallel to update a specific Smartsheet object results in reduced performance and often results in errors due to save collisions. To avoid this scenario, design your integration such that API requests to update a specific Smartsheet object are always executed serially (that is, execute one request at time, not beginning the next request until the previous request has completed).
API Reference
Attachments
Attachments can exist on a comment (that is, within a discussion), on a row, or on a sheet.
Objects
Attachment Object
Example: Attachment object
{
"id": 4539352454850436,
"name": "at3.pdf",
"url": "https://www.example.com",
"attachmentType": "FILE",
"mimeType": "application/pdf",
"urlExpiresInMillis": 120000,
"sizeInKb": 56,
"createdBy": {
"name": "Jane Roe",
"email": "jane.roe@company.com"
},
"createdAt": "2017-06-09T17:41:05Z"
}
id | number | Attachment Id |
parentId | number | The Id of the parent |
attachmentType | string | Attachment type (one of BOX_COM, DROPBOX*, EGNYTE*, EVERNOTE*, FILE, GOOGLE_DRIVE, LINK, or ONEDRIVE) *Not supported for all account types, see below. |
attachmentSubType | string | Attachment sub type, valid only for the following:
|
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:
|
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:
|
Content-Type | Can be left blank if it is not known (but must be present); Smartsheet makes its best guess based on the extension of the file. |
The following example request shows a simple upload that adds a file attachment to a sheet:
POST https://api.smartsheet.com/2.0/sheets/4509093797881732/attachments
Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Disposition: attachment; filename="ProgressReport.docx"
Content-Type: application/msword
Content-Length: 5463
< Binary content for file >
As shown in this example, the contents of the file is included in the body of the POST
request. In most programming languages, this is done by reading the file from an input stream and writing it out to the output stream of the HTTP request.
Attach File to Comment
Example request: attach file to comment
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx
// Enable FileStream
var fs = require("fs")
// Set options
var options = {
sheetId: 1696803624483716,
commentId: 7722333183016324,
fileSize: 20765,
fileName: "ProgressReport.docx",
fileStream: fs.createReadStream("/Users/jdoe/Documents/ProgressReport.docx")
};
// Attach file to comment
smartsheet.sheets.addCommentFileAttachment(options)
.then(function(attachment) {
console.log(attachment);
})
.catch(function(error) {
console.log(error);
});
Attachment attachment = smartsheet.SheetResources.CommentResources.AttachmentResources.AttachFile(
9283173393803140, // sheetId
1234567890234568, // commentId
filePath,
"application/msword"
);
// Specify file to be attached
File file = new File("/Users/jdoe/Documents/ProgressReport.docx");
// Attach file to comment
Attachment attachment = smartsheet.sheetResources().commentResources().attachmentResources().attachFile(
9283173393803140L, // long sheetId
1234567890234568L, // long commentId
file,
"application/msword"
);
updated_attachment = smartsheet_client.Attachments.attach_file_to_comment(
9283173393803140, # sheet_id
1234567890234568, # comment_id
('ProgressReport.docx',
open('/path/to/ProgressReport.docx', 'rb'),
'application/msword')
)
# Sample 1: attach file from path
response = smartsheet.sheets.comments.attachments.attach_file_from_path(
sheet_id: 4583173393803140,
comment_id: 4293147074291588,
path: '/Users/jdoe/Documents/ProgressReport.docx'
)
new_attachment = response[:result]
# Sample 2: attach file
filename = '/Users/jdoe/Documents/ProgressReport.docx'
file = File.open(filename)
file_length = File.size(filename)
response = smartsheet.sheets.comments.attachments.attach_file(
sheet_id: 4583173393803140,
comment_id: 4293147074291588,
file: file,
filename: filename,
file_length: file_length
)
new_attachment = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 4583173393803140,
"name": "ProgressReport.docx",
"attachmentType": "FILE",
"mimeType": "application/msword",
"createdAt": "2013-02-28T21:04:56-08:00"
},
"version": 12
}
POST /sheets/{sheetId}/comments/{commentId}/attachments
Attaches a file to the comment. This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment.
This operation always creates a new attachment. To upload a new version of the same attachment, use the Attach New Version operation.
Headers | Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Post an Attachment for details. |
Request Body | Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Post an Attachment for details. |
Returns | Result object containing an Attachment object for the newly created attachment |
Access Scope | WRITE_SHEETS |
Attach File to Row
Example request: attach file to row
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx
// Enable FileStream
var fs = require("fs")
// Set options
var options = {
sheetId: 1696803624483716,
rowId: 1049041355358596,
fileSize: 20765,
fileName: "ProgressReport.docx",
fileStream: fs.createReadStream("/Users/jdoe/Documents/ProgressReport.docx")
};
// Attach file to row
smartsheet.sheets.addRowFileAttachment(options)
.then(function(attachment) {
console.log(attachment);
})
.catch(function(error) {
console.log(error);
});
Attachment attachment = smartsheet.SheetResources.RowResources.AttachmentResources.AttachFile(
9283173393803140, // sheetId
0123456789012345, // rowId
filePath,
"application/msword"
);
// Specify file to be attached
File file = new File("/Users/jdoe/Documents/ProgressReport.docx");
// Attach file to row
Attachment attachment = smartsheet.sheetResources().rowResources().attachmentResources().attachFile(
9283173393803140L, // long sheetId
0123456789012345L, // long rowId
file,
"application/msword"
);
updated_attachment = smartsheet_client.Attachments.attach_file_to_row(
9283173393803140, # sheet_id
0123456789012345, # row_id
('ProgressReport.docx',
open('/path/to/ProgressReport.docx', 'rb'),
'application/msword')
)
# Sample 1: Attach file from path
response = smartsheet.sheets.rows.attachments.attach_file_from_path(
sheet_id: 4583173393803140,
row_id: 4293147074291588,
path: '/Users/jdoe/Documents/ProgressReport.docx'
)
new_attachment = response[:result]
# Sample 2: Attach file
filename = '/Users/jdoe/Documents/ProgressReport.docx'
file = File.open(filename)
file_length = File.size(filename)
response = smartsheet.sheets.rows.attachments.attach_file(
sheet_id: 4583173393803140,
row_id: 4293147074291588,
file: file,
filename: filename,
file_length: file_length
)
new_attachment = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 4583173393803140,
"name": "ProgressReport.docx",
"attachmentType": "FILE",
"mimeType": "application/msword",
"createdAt": "2013-02-28T21:04:56-08:00"
},
"version": 12
}
POST /sheets/{sheetId}/rows/{rowId}/attachments
Attaches a file to the row. This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment.
This operation always creates a new attachment. To upload a new version of the same attachment, use the Attach New Version operation.
Headers | Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Post an Attachment for details. |
Request Body | Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Post an Attachment for details. |
Returns | Result object containing an Attachment object for the newly created attachment |
Access Scope | WRITE_SHEETS |
Attach File to Sheet
Example request: attach file to sheet
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx
// Enable FileStream
var fs = require("fs")
// Set options
var options = {
sheetId: 1694401624483716,
fileSize: 20765,
fileName: "ProgressReport.docx",
fileStream: fs.createReadStream("/Users/jdoe/Documents/ProgressReport.docx")
};
// Attach file to sheet
smartsheet.sheets.addFileAttachment(options)
.then(function(attachment) {
console.log(attachment);
})
.catch(function(error) {
console.log(error);
});
Attachment attachment = smartsheet.SheetResources.AttachmentResources.AttachFile(
9283173393803140, // sheetId
filePath,
"application/msword"
);
// Specify file to be attached
File file = new File("/Users/jdoe/Documents/ProgressReport.docx");
// Attach file to sheet
Attachment attachment = smartsheet.sheetResources().attachmentResources().attachFile(
9283173393803140L, // long sheetId
file,
"application/msword"
);
updated_attachment = smartsheet_client.Attachments.attach_file_to_sheet(
9283173393803140, # sheet_id
('ProgressReport.docx',
open('/path/to/ProgressReport.docx', 'rb'),
'application/msword')
)
# Sample 1: Attach file from path
response = smartsheet.sheets.attachments.attach_file_from_path(
sheet_id: 4583173393803140,
path: '/Users/jdoe/Documents/ProgressReport.docx'
)
new_attachment = response[:result]
# Sample 2: Attach file
filename = '/Users/jdoe/Documents/ProgressReport.docx'
file = File.open(filename)
file_length = File.size(filename)
response = smartsheet.sheets.attachments.attach_file(
sheet_id: 4583173393803140,
file: file,
filename: filename,
file_length: file_length
)
new_attachment = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 4583173393803140,
"name": "ProgressReport.docx",
"attachmentType": "FILE",
"mimeType": "application/msword",
"createdAt": "2013-02-28T21:04:56-08:00"
},
"version": 12
}
POST /sheets/{sheetId}/attachments
Attaches a file to the sheet. This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment.
This operation always creates a new attachment. To upload a new version of the same attachment, use the Attach New Version operation.
Headers | Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Post an Attachment for details. |
Request Body | Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Post an Attachment for details. |
Returns | Result object containing an Attachment object for the newly created attachment |
Access Scope | WRITE_SHEETS |
Attach URL to Comment
Example request: attach URL to comment
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "attachmentType":"LINK", "url":"http://www.google.com"}'
// Specify URL attachment
var attachment = {
"name": "Search Engine",
"attachmentType": "LINK",
"url": "http://www.google.com"
};
// Set options
var options = {
sheetId: 2252168947361668,
commentId: 4445024629876612,
body: attachment
};
// Attach URL to comment
smartsheet.sheets.addCommentAttachment(options)
.then(function(updatedAttachment) {
console.log(updatedAttachment);
})
.catch(function(error) {
console.log(error);
});
// Create attachment
Attachment attachmentSpecification = new Attachment
{
Url = "http://www.google.com",
AttachmentType = AttachmentType.LINK,
Name = "Search Engine"
};
// Attach URL to comment
Attachment updatedAttachment = smartsheet.SheetResources.CommentResources.AttachmentResources.AttachUrl(
9283173393803140, // sheetId
0123456789012345, // commentId
attachmentSpecification
);
// Create attachment
Attachment attachmentSpecification = new Attachment();
attachmentSpecification.setAttachmentType(AttachmentType.LINK)
.setUrl("http://www.google.com")
.setName("Search Engine");
// Attach URL to comment
Attachment updatedAttachment = smartsheet.sheetResources().commentResources().attachmentResources().attachUrl(
9283173393803140L, // long sheetId
0123456789012345L, // long commentId
attachmentSpecification
);
# Create URL attachment
url_spec = smartsheet.models.Attachment({
'name': 'Search Engine',
'attachment_type': 'LINK',
'url': 'http://www.google.com'
})
# Attach URL to comment
updated_attachment = smartsheet_client.Attachments.attach_url_to_comment(
9283173393803140, # sheet_id
0123456789012345, # comment_id
url_spec)
# Specify options
body = {
name: 'A URL',
url: 'https://google.com',
attachment_type: 'LINK'
}
# Attach URL to comment
response = smartsheet.sheets.comments.attachments.attach_url(
sheet_id: 4583173393803140,
comment_id: 4293147074291588,
body: body
)
new_attachment = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"attachmentType": "LINK",
"createdAt": "2013-02-28T21:52:40-08:00",
"description": "A popular search engine",
"id": 1205473673275268,
"name": "Search Engine",
"url": "http://google.com"
}
}
POST /sheets/{sheetId}/comments/{commentId}/attachments
Attaches a URL to the comment.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Attachment object limited to the following attributes:
|
Returns | Result object containing an Attachment object for the newly created attachment |
Access Scope | WRITE_SHEETS |
The URL can be any of the following:
- Normal URL (attachmentType "LINK")
- Box.com URL (attachmentType "BOX_COM")
- Dropbox URL (attachmentType "DROPBOX")
- Egnyte URL (attachmentType "EGNYTE")
- Evernote URL (attachmentType "EVERNOTE")
- Google Drive URL (attachmentType "GOOGLE_DRIVE")
- OneDrive URL (attachmentType "ONEDRIVE")
Attach URL to Row
Example request: attach URL to row
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'
// Specify URL attachment
var attachment = {
"name": "Search Engine",
"description": "A popular search engine",
"attachmentType": "LINK",
"url": "http://www.google.com"
};
// Set options
var options = {
sheetId: 2252168947361668,
rowId: 4293147074291588,
body: attachment
};
// Attach URL to row
smartsheet.sheets.addRowAttachment(options)
.then(function(updatedAttachment) {
console.log(updatedAttachment);
})
.catch(function(error) {
console.log(error);
});
// Create attachment
Attachment attachmentSpecification = new Attachment
{
Url = "http://www.google.com",
AttachmentType = AttachmentType.LINK,
Name = "Search Engine"
};
// Attach URL to row
Attachment updatedAttachment = smartsheet.SheetResources.RowResources.AttachmentResources.AttachUrl(
9283173393803140, // sheetId
0123456789012345, // rowId
attachmentSpecification
);
// Create attachment
Attachment attachmentSpecification = new Attachment();
attachmentSpecification.setAttachmentType(AttachmentType.LINK)
.setUrl("http://www.google.com")
.setDescription("A popular search engine")
.setName("Search Engine");
// Attach URL to row
Attachment updatedAttachment = smartsheet.sheetResources().rowResources().attachmentResources().attachUrl(
9283173393803140L, // long sheetId
0123456789012345L, // long rowId
attachmentSpecification
);
# Create URL attachment
url_spec = smartsheet.models.Attachment({
'name': 'Search Engine',
'description': 'A popular search engine.'
'attachment_type': 'LINK',
'url': 'http://www.google.com'
})
# Attach URL to row
updated_attachment = smartsheet_client.Attachments.attach_url_to_row(
9283173393803140, # sheet_id
0123456789012345, # row_id
url_spec)
# Specify options
body = {
name: 'Search here',
description: 'A search engine',
url: 'https://google.com',
attachment_type: 'LINK'
}
# Attach URL to row
response = smartsheet.sheets.rows.attachments.attach_url(
sheet_id: 4583173393803140,
row_id: 4293147074291588,
body: body
)
new_attachment = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"attachmentType": "LINK",
"createdAt": "2013-02-28T21:52:40-08:00",
"description": "A popular search engine",
"id": 1205473673275268,
"name": "Search Engine",
"url": "http://google.com"
}
}
POST /sheets/{sheetId}/rows/{rowId}/attachments
Attaches a URL to the row.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Attachment object limited to the following attributes:
|
Returns | Result object containing an Attachment object for the newly created attachment |
Access Scope | WRITE_SHEETS |
The URL can be any of the following:
- Normal URL (attachmentType "LINK")
- Box.com URL (attachmentType "BOX_COM")
- Dropbox URL (attachmentType "DROPBOX")
- Egnyte URL (attachmentType "EGNYTE")
- Evernote URL (attachmentType "EVERNOTE")
- Google Drive URL (attachmentType "GOOGLE_DRIVE")
- OneDrive URL (attachmentType "ONEDRIVE")
Attach URL to Sheet
Example request: attach URL to sheet
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'
// Specify URL attachment
var attachment = {
"name": "Search Engine",
"description": "A popular search engine",
"attachmentType": "LINK",
"url": "http://www.google.com"
};
// Set options
var options = {
sheetId: 2252168947361668,
body: attachment
};
// Attach URL to sheet
smartsheet.sheets.addAttachment(options)
.then(function(updatedAttachment) {
console.log(updatedAttachment);
})
.catch(function(error) {
console.log(error);
});
// Create attachment
Attachment attachmentSpecification = new Attachment
{
Url = "http://www.google.com",
AttachmentType = AttachmentType.LINK,
Name = "Search Engine",
Description = "A popular search engine"
};
// Attach URL to sheet
Attachment updatedAttachment = smartsheet.SheetResources.AttachmentResources.AttachUrl(
9283173393803140, // sheetId
attachmentSpecification
);
// Create attachment
Attachment attachmentSpecification = new Attachment();
attachmentSpecification.setAttachmentType(AttachmentType.LINK)
.setUrl("http://www.google.com")
.setDescription("A popular search engine")
.setName("Search Engine");
// Attach URL to sheet
Attachment updatedAttachment = smartsheet.sheetResources().attachmentResources().attachUrl(
9283173393803140L, // long sheetId
attachmentSpecification
);
# Create URL attachment
url_spec = smartsheet.models.Attachment({
'name': 'Search Engine',
'description': 'A popular search engine.',
'attachment_type': 'LINK',
'url': 'http://www.google.com'
})
# Attach URL to sheet
updated_attachment = smartsheet_client.Attachments.attach_url_to_sheet(
9283173393803140, # sheet_id
url_spec)
# Specify options
body = {
name: 'Search Engine',
description: 'A popular search engine.',
url: 'http://www.google.com',
attachment_type: 'LINK'
}
# Attach URL to sheet
response = smartsheet.sheets.attachments.attach_url(
sheet_id: 4583173393803140,
body: body
)
new_attachment = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"attachmentType": "LINK",
"createdAt": "2013-02-28T21:52:40-08:00",
"description": "A popular search engine",
"id": 1205473673275268,
"name": "Search Engine",
"url": "http://google.com"
}
}
POST /sheets/{sheetId}/attachments
Attaches a URL to the sheet.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Attachment object limited to the following attributes:
|
Returns | Result object containing an Attachment object for the newly created attachment |
Access Scope | WRITE_SHEETS |
The URL can be any of the following:
- Normal URL (attachmentType "LINK")
- Box.com URL (attachmentType "BOX_COM")
- Dropbox URL (attachmentType "DROPBOX")
- Egnyte URL (attachmentType "EGNYTE")
- Evernote URL (attachmentType "EVERNOTE")
- Google Drive URL (attachmentType "GOOGLE_DRIVE")
- OneDrive URL (attachmentType "ONEDRIVE")
Delete Attachment
Example request: delete attachment
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
sheetId: 2252168947361668,
attachmentId: 7169782752536452,
};
// Delete attachment
smartsheet.sheets.deleteAttachment(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.SheetResources.AttachmentResources.DeleteAttachment(
9283173393803140, // sheetId
7169782752536452 // attachmentId
);
smartsheet.sheetResources().attachmentResources().deleteAttachment(
9283173393803140L, // long sheetId
7169782752536452L // sheetAttachmentId
);
smartsheet_client.Attachments.delete_attachment(
9283173393803140, # sheet_id
7169782752536452) # attachment_id
smartsheet.sheets.attachments.delete(
sheet_id: 4583173393803140,
attachment_id: 7169782752536452
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /sheets/{sheetId}/attachments/{attachmentId}
Deletes the attachment specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | WRITE_SHEETS |
Get Attachment
Example request: get attachment
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 9283173393803140,
attachmentId: 4583173393803140
};
// Get attachment
smartsheet.sheets.getAttachment(options)
.then(function(attachment) {
console.log(attachment);
})
.catch(function(error) {
console.log(error);
});
Attachment attachment = smartsheet.SheetResources.AttachmentResources.GetAttachment(
9283173393803140, // sheetId
4583173393803140 // attachmentId
);
Attachment attachment = smartsheet.sheetResources().attachmentResources().getAttachment(
9283173393803140L, // long sheetId
4583173393803140L // long attachmentId
);
attachment = smartsheet_client.Attachments.get_attachment(
9283173393803140, # sheet_id
4583173393803140) # attachment_id
attachment = smartsheet.sheets.attachments.get(
sheet_id: 9283173393803140,
attachment_id: 4583173393803140
)
Example response
{
"name": "expense_report_sample.png",
"url": "https://api.smartsheet.com/download/aa402974cdb74cb58d9",
"attachmentType": "FILE",
"mimeType": "image/png",
"id": 4583173393803140,
"urlExpiresInMillis": 120000
}
GET /sheets/{sheetId}/attachments/{attachmentId}
Fetches a temporary URL that allows you to download an attachment. The urlExpiresInMillis attribute tells you how long the URL is valid.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Attachment object. For file attachments, this includes a temporary URL for downloading the file. Currently, the temporary URL is set to expire in 120000 milliseconds, or 2 minutes. |
Access Scope | READ_SHEETS |
List Attachments
Example request: list attachments
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 9283173393803140
};
// List attachments
smartsheet.sheets.listAttachments(options)
.then(function(attachmentsList) {
console.log(attachmentsList);
})
.catch(function(error) {
console.log(error);
});
// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.AttachmentResources.ListAttachments(
9283173393803140, // sheetId
null // PaginationParameters
);
// Omit pagination
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().listAttachments(
9283173393803140L, // long sheetId
null // PaginationParameters
);
# Sample 1: List All
response = smartsheet_client.Attachments.list_all_attachments(
9283173393803140, # sheet_id
include_all=True)
attachments = response.data
# Sample 2: Paginate the list of attachments
response = smartsheet_client.Attachments.list_all_attachments(
9283173393803140, # sheet_id
page_size=10,
page=1)
pages = response.total_pages
attachments = response.data
response = smartsheet.sheets.attachments.list(
sheet_id: 9283173393803140
)
attachments = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [
{
"name": "att3.png",
"attachmentType": "FILE",
"mimeType": "image/png",
"id": 4583173393803140,
"parentType" : "SHEET",
"parentId" : 341847495283
},
{
"name": "att4.png",
"attachmentType": "FILE",
"mimeType": "image/png",
"id": 7993173393803140,
"parentType" : "ROW",
"parentId" : 684956754834557
}
]
}
GET /sheets/{sheetId}/attachments
Gets a list of all attachments that are on the sheet, including sheet, row, and discussion-level attachments.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. |
Returns | IndexResult object containing an array of Attachment objects |
Access Scope | READ_SHEETS |
List Discussion Attachments
Example request: list discussion attachments
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 2252168947361668,
discussionId: 3962273862576004
};
// List discussion attachments
smartsheet.sheets.listDiscussionAttachments(options)
.then(function(attachmentsList) {
console.log(attachmentsList);
})
.catch(function(error) {
console.log(error);
});
// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.DiscussionResources.AttachmentResources.ListAttachments(
9283173393803140, // sheetId
1234567890123456, // discussionId
null // PaginationParameters
);
// Omit pagination
PagedResult<Attachment> attachments = smartsheet.sheetResources().discussionResources().attachmentResources().getAttachments(
9283173393803140L, // long sheetId
1234567890123456L, // long discussionId
null // PaginationParameters
);
# Sample 1: List All
response = smartsheet_client.Attachments.list_discussion_attachments(
9283173393803140, # sheet_id
1234567890123456, # discussion_id
include_all=True)
attachments = response.data
# Sample 2: Paginate the list
response = smartsheet_client.Attachments.list_discussion_attachments(
9283173393803140, # sheet_id
1234567890123456, # discussion_id
page_size=10,
page=1)
pages = response.total_pages
attachments = response.data
response = smartsheet.sheets.discussions.attachments.list(
sheet_id: 9283173393803140,
discussion_id: 1234567890123456
)
attachments = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [
{
"name": "att3.png",
"attachmentType": "FILE",
"mimeType": "image/png",
"id": 4583173393803140,
"parentType" : "COMMENT",
"parentId" : 341847495283
},
{
"name": "att4.png",
"attachmentType": "FILE",
"mimeType": "image/png",
"id": 7993173393803140,
"parentType" : "COMMENT",
"parentId" : 684956754834557
}
]
}
GET /sheets/{sheetId}/discussions/{discussionId}/attachments
Gets a list of all attachments that are in the discussion.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. |
Returns | IndexResult object containing an array of Attachment objects |
Access Scope | READ_SHEETS |
List Row Attachments
Example request: list row attachments
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 2252168947361668,
rowId: 4293147074291588
};
// List row attachments
smartsheet.sheets.getRowAttachments(options)
.then(function(attachmentsList) {
console.log(attachmentsList);
})
.catch(function(error) {
console.log(error);
});
// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.RowResources.AttachmentResources.ListAttachments(
2252168947361668, // sheetId
4293147074291588, // rowId
null // PaginationParameters
);
// Omit pagination
PagedResult<Attachment> attachments = smartsheet.sheetResources().rowResources().attachmentResources().getAttachments(
2252168947361668L, // long sheetId
4293147074291588L, // long rowId
null // PaginationParameters
);
# Sample 1: List all
response = smartsheet_client.Attachments.list_row_attachments(
2252168947361668, # sheet_id
4293147074291588, # row_id
include_all=True)
attachments = response.data
# Sample 2: Paginate the list
response = smartsheet_client.Attachments.list_row_attachments(
2252168947361668, # sheet_id
4293147074291588, # row_id
page_size=10,
page=1)
pages = response.total_pages
attachments = response.data
response = smartsheet.sheets.rows.attachments.list(
sheet_id: 2252168947361668,
row_id: 4293147074291588
)
attachments = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [
{
"name": "att3.png",
"attachmentType": "FILE",
"mimeType": "image/png",
"id": 4583173393803140,
"parentType" : "ROW",
"parentId" : 341847495283
},
{
"name": "att4.png",
"attachmentType": "FILE",
"mimeType": "image/png",
"id": 7993173393803140,
"parentType" : "COMMENT",
"parentId" : 684956754834557
}
]
}
GET /sheets/{sheetId}/rows/{rowId}/attachments
Gets a list of all attachments that are on the row, including row and discussion-level attachments.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. |
Returns | IndexResult object containing an array of Attachment objects |
Access Scope | READ_SHEETS |
Versioning
Attach New Version
Example request: attach new version
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx
// Enable FileStream
var fs = require("fs")
// Set options
var options = {
sheetId: 9283173393803140,
attachmentId: 0123456789123456,
fileSize: 17291,
fileName: "ProgressReport.docx",
fileStream: fs.createReadStream("/Users/jdoe/Documents/ProgressReport.docx")
};
// Attach new version
smartsheet.sheets.attachNewVersion(options)
.then(function(updatedAttachment) {
console.log(updatedAttachment);
})
.catch(function(error) {
console.log(error);
});
Attachment attachment = smartsheet.SheetResources.AttachmentResources.VersioningResources.AttachNewVersion(
9283173393803140, // sheetId
0123456789123456, // attachmentId
filePath,
"application/msword"
);
// Specify the new file to be attached
File file = new File("/Users/jdoe/Documents/ProgressReport.docx");
// Attach new version of the file
Attachment attachment = smartsheet.sheetResources().attachmentResources().versioningResources().attachNewVersion(
9283173393803140L, // long sheetId
0123456789123456L, // long attachmentId
file,
"application/msword"
);
response = smartsheet_client.Attachments.attach_new_version(
9283173393803140, # sheet_id
0123456789123456, # attachment_id
('ProgressReport.docx',
open('/path/to/ProgressReport.docx', 'rb'),
'application/msword')
)
updated_attachment = response.result
# Sample 1: Attach new version from path
response = smartsheet.sheets.attachments.attach_new_version_from_path(
sheet_id: 9283173393803140,
attachment_id: 0123456789123456,
path: '/Users/jdoe/Documents/ProgressReport.docx'
)
updated_attachment = response[:result]
# Sample 2: Attach new version
filename = '/Users/jdoe/Documents/ProgressReport.docx'
file = File.open(filename)
file_length = File.size(filename)
response = smartsheet.sheets.attachments.attach_new_version(
sheet_id: 9283173393803140,
attachment_id: 0123456789123456,
file: file,
filename: filename,
file_length: file_length
)
updated_attachment = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 4583173393803140,
"name": "ProgressReport.docx",
"attachmentType": "FILE",
"mimeType": "application/msword",
"createdAt": "2013-02-28T21:04:56-08:00"
},
"version": 12
}
POST /sheets/{sheetId}/attachments/{attachmentId}/versions
Uploads a new version of a file to a sheet or row. This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment.
Headers | Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Post an Attachment for details. |
Request Body | Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Post an Attachment for details. |
Returns | Result object containing an Attachment object for the newly created attachment |
Access Scope | WRITE_SHEETS |
Delete All Versions
Example request: delete all versions
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
sheetId: 2252168947361668,
attachmentId: 5510069950408580
};
// Delete all versions of the attachment
smartsheet.sheets.deleteAllAttachmentVersions(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.SheetResources.AttachmentResources.VersioningResources.DeleteAllVersions(
9283173393803140, // sheetId
0123456789123456 // attachmentId
);
smartsheet.sheetResources().attachmentResources().versioningResources().deleteAllVersions(
9283173393803140L, // long sheetId
0123456789123456L // long attachmentId
);
smartsheet_client.Attachments.delete_attachment_versions(
9283173393803140, # sheet_id
0123456789123456) # attachment_id
smartsheet.sheets.attachments.delete_all_versions(
sheet_id: 9283173393803140,
attachment_id: 0123456789123456
)
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"version": 12
}
DELETE /sheets/{sheetId}/attachments/{attachmentId}/versions
Deletes all versions of the attachment corresponding to the specified attachmentId. For attachments with multiple versions, this effectively deletes the attachment from the object that it’s attached to.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | WRITE_SHEETS |
List Versions
Example request: list versions
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 2252168947361668,
attachmentId: 5510069950408580
};
// List versions of the attachment
smartsheet.sheets.listAttachmentVersions(options)
.then(function(versionList) {
console.log(versionList);
})
.catch(function(error) {
console.log(error);
});
// Omit pagination parameters
PaginatedResult<Attachment> attachments = smartsheet.SheetResources.AttachmentResources.VersioningResources.ListVersions(
2252168947361668, // sheetId
5510069950408580, // attachmentId
null // PaginationParameters
);
// Omit pagination
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().versioningResources().listAllVersions(
2252168947361668L, // long sheetId
5510069950408580L, // long attachmentId
null // PaginationParameters
);
# Sample 1: List all
response = smartsheet_client.Attachments.list_attachment_versions(
2252168947361668, # sheet_id
5510069950408580, # attachment_id
include_all=True)
versions = response.data
# Sample 2: Paginate the list
response = smartsheet_client.Attachments.list_attachment_versions(
2252168947361668, # sheet_id
5510069950408580, # attachment_id
page_size=5,
page=1)
pages = response.total_pages
versions = response.data
response = smartsheet.sheets.attachments.list_versions(
sheet_id: 4583173393803140,
attachment_id: 5510069950408580
)
versions = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [
{
"id": 4583173393803140,
"name": "at3.png",
"attachmentType": "file",
"mimeType": "image/png",
"createdAt": "2014-03-28T18:13:20-07:00"
},
{
"id": 642523719853956,
"name": "at3.png",
"attachmentType": "file",
"mimeType": "image/png",
"createdAt": "2014-03-27T18:11:11-07:00"
}
]
}
GET /sheets/{sheetId}/attachments/{attachmentId}/versions
Gets a list of all versions of the given attachmentId in order from newest to oldest.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. |
Returns | IndexResult object containing an array of Attachment objects |
Access Scope | READ_SHEETS |
Automation Rules
Automation is a catch-all term for approvals, notifications, and update requests. You can delete, update, or retrieve various automation settings through the API. You cannot create new automation rules programmatically.
Objects
AutomationRule Object
Example: AutomationRule object
{
"id": 789994550205316,
"name": "Approval Request",
"enabled": true,
"createdBy": {
"email": "john.doe@smartsheet.com"
},
"createdAt": "2017-12-14T18:31:55Z",
"modifiedBy": {
"email": "john.doe@smartsheet.com"
},
"modifiedAt": "2017-12-14T18:31:55Z",
"userCanModify": true,
"action": {
"type": "APPROVAL_REQUEST_ACTION",
"recipients": [
{
"email": "jane.roe@smartsheet.com"
}
],
"frequency": "IMMEDIATELY",
"includeAllColumns": true,
"includeAttachments": true,
"includeDiscussions": true,
"notifyAllSharedUsers": false
}
}
id | number | AutomationRule Id |
action | AutomationAction | AutomationAction object containing information for this rule, such as type, recipients, and frequency. |
createdAt | timestamp | A timestamp of when the rule was originally added. |
createdBy | User | User object containing name and email of the creator of this rule. |
disabledReason | string | Machine-readable reason a rule is disabled. See table of Disabled Reasons. |
disabledReasonText | string | Descriptive reason a rule is disabled. |
enabled | Boolean | If true, indicates that the rule is active. |
modifiedAt | timestamp | The datetime for when the change was made to the rule. |
modifiedBy | User | User object containing the name and email of the user that made the change. |
name | string | Rule name as shown in the UI. |
userCanModify | Boolean | If true, indicates that the current user can modify the rule. |
AutomationAction Object
Example: AutomationAction object
{
"type": "APPROVAL_REQUEST_ACTION",
"recipients": [
{
"email": "jane.roe@smartsheet.com"
}
],
"frequency": "IMMEDIATELY",
"includeAllColumns": true,
"includeAttachments": true,
"includeDiscussions": true,
"notifyAllSharedUsers": false
}
includedColumnIds | long[] | Specifies which columns to include in message. |
recipientColumnIds | long[] | Array of column Ids from which to collect email recipients. |
type | string | One of three types: APPROVAL_REQUEST_ACTION, NOTIFICATION_ACTION, or UPDATE_REQUEST_ACTION. |
frequency | string | Must be one of the following values: DAILY, HOURLY, IMMEDIATELY, or WEEKLY. Ignored for date-based rules. |
includeAllColumns | Boolean | If true (default), all columns are included in email contents. |
includeAttachments | Boolean | If true, includes attachments. |
includeDiscussions | Boolean | If true, includes discussions. |
message | string | Email body. |
notifyAllSharedUsers | Boolean | If true, notifications are sent to all users shared to the sheet. |
recipients | Recipient | Array of Recipient objects that contains one or more Email objects. |
subject | string | Email subject line. |
Delete an Automation Rule
Example request: delete an automation rule
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
sheetId: 9283173393803140,
automationRuleId: 789004550205316
};
// Delete automation rule
smartsheet.sheets.deleteAutomationRule(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
AutomationRule automationRule = smartsheet.SheetResources.AutomationRuleResources.DeleteAutomationRule(
9283173393803140, // sheetId
789004550205316 // automationRuleId
);
// Not yet implemented
# Not yet implemented
smartsheet.sheets.automation_rules.delete(
sheet_id: 9283173393803140,
automation_rule_id: 789004550205316
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /sheets/{sheetId}/automationrules/{automationRuleId}
Deletes an automation rule.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | WRITE_SHEETS |
Get an Automation Rule
Example request: get an automation rule
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 9283173393803140,
automationRuleId: 789994550205316
};
// Get automation rule
smartsheet.sheets.getAutomationRule(options)
.then(function(automationRule) {
console.log(automationRule);
})
.catch(function(error) {
console.log(error);
});
AutomationRule automationRule = smartsheet.SheetResources.GetAutomationRule(
9283173393803140, // sheetId
789994550205316 // automationRuleId
);
// Not yet implemented
# Not yet implemented
rule = smartsheet.sheets.automation_rules.get(
sheet_id: 9283173393803140,
automation_rule_id: 789994550205316
)
Example response
{
"id": 789994550205316,
"name": "Approval Request",
"enabled": true,
"createdBy": {
"email": "john.doe@smartsheet.com"
},
"createdAt": "2017-12-14T18:31:55Z",
"modifiedBy": {
"email": "john.doe@smartsheet.com"
},
"modifiedAt": "2017-12-14T18:31:55Z",
"userCanModify": true,
"action": {
"type": "APPROVAL_REQUEST_ACTION",
"recipients": [
{
"email": "jane.roe@smartsheet.com"
}
],
"frequency": "IMMEDIATELY",
"includeAllColumns": true,
"includeAttachments": true,
"includeDiscussions": true,
"notifyAllSharedUsers": false
}
}
GET /sheets/{sheetId}/automationrules/{automationRuleId}
Returns the specified automation rule, including any action values.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | AutomationRule object. |
Access Scope | READ_SHEETS |
List All Automation Rules
Example request: list all automation rules
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 9283173393803140
};
// List automation rules
smartsheet.sheets.listAutomationRules(options)
.then(function(automationRulesList) {
console.log(automationRulesList);
})
.catch(function(error) {
console.log(error);
});
PaginatedResult<AutomationRule> AutomationRules = smartsheet.SheetResources.AutomationRuleResources.ListAutomationRules(
9283173393803140, // sheetId
null // PaginationParameters
);
// Not yet implemented
# Not yet implemented
response = smartsheet.sheets.automation_rules.list(
sheet_id: 9283173393803140
)
rules = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [
{
"id": 789994550205316,
"name": "Approval Request",
"enabled": true,
"createdBy": {
"email": "john.doe@smartsheet.com"
},
"createdAt": "2017-12-14T18:31:55Z",
"modifiedBy": {
"email": "john.doe@smartsheet.com"
},
"modifiedAt": "2017-12-14T18:31:55Z",
"userCanModify": true,
"action": {
"type": "APPROVAL_REQUEST_ACTION",
"recipients": [
{
"email": "jane.roe@smartsheet.com"
}
],
"frequency": "IMMEDIATELY",
"includeAllColumns": true,
"includeAttachments": true,
"includeDiscussions": true,
"notifyAllSharedUsers": false
}
},
{
"id": 3377755522834820,
"name": "Notification",
"enabled": true,
"createdBy": {
"email": "john.doe@smartsheet.com"
},
"createdAt": "2017-12-14T18:31:37Z",
"modifiedBy": {
"email": "john.doe@smartsheet.com"
},
"modifiedAt": "2017-12-14T18:31:37Z",
"userCanModify": true,
"action": {
"type": "NOTIFICATION_ACTION",
"recipients": [
{
"email": "jane.roe@smartsheet.com"
}
],
"frequency": "DAILY",
"includeAllColumns": true,
"includeAttachments": true,
"includeDiscussions": true,
"notifyAllSharedUsers": false
}
}
]
}
GET /sheets/{sheetId}/automationrules
Returns all automation rules associated with the specified sheet.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | IndexResult object containing an array of AutomationRule objects. |
Access Scope | READ_SHEETS |
Update an Automation Rule
Example request: update an automation rule
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X PUT \
-d '{
"action": {
"type": "APPROVAL_REQUEST_ACTION",
"recipients": [{
"email": "jane.roe@smartsheet.com"
}],
"frequency": "WEEKLY"
}
}'
// Specify the changes
var body = {
"name": "Approval Request",
"action": {
"type": "APPROVAL_REQUEST_ACTION",
"recipients": [
{
"email": "jane.roe@smartsheet.com"
}
],
"frequency": "WEEKLY",
"includeAllColumns": true,
"includeAttachments": true,
"includeDiscussions": true,
"notifyAllSharedUsers": false
}
};
// Set options
var options = {
sheetId: 4583173393803140,
automationRuleId: 789994550205316,
body: body
};
// Update the automation rule
smartsheet.sheets.updateAutomationRule(options)
.then(function(updatedAutomationRule) {
console.log(updatedAutomationRule);
})
.catch(function(error) {
console.log(error);
});
// Set recipient
Recipient recipient = new Recipient
{
Email = "jane.roe@smartsheet.com"
};
// Specify the changes
AutomationRule autoRule = new AutomationRule
{
Id = 789994550205316,
Action = new AutomationAction
{
Recipients = new[] { recipient },
Type = AutomationActionType.NOTIFICATION_ACTION,
Frequency = AutomationActionFrequency.WEEKLY
}
};
// Update the automation rule
AutomationRule automationRule = smartsheet.SheetResources.UpdateAutomationRule(
4583173393803140, // sheetId
autoRule
);
// Not yet implemented
# Not yet implemented
smartsheet.sheets.automation_rules.update(
sheet_id: 4583173393803140,
automation_rule_id: 789994550205316,
body: {
name: 'Approval Request',
enabled: true,
action: {
type: 'APPROVAL_REQUEST_ACTION',
recipients: [
{
email: 'jane.roe@smartsheet.com'
}
],
frequency: 'WEEKLY',
include_all_columns: true,
include_attachments: true,
include_discussions: true,
notify_all_shared_users: false
}
})
Example response
{
"id": 789994550205316,
"name": "Approval Request",
"enabled": true,
"createdBy": {
"email": "john.doe@smartsheet.com"
},
"createdAt": "2017-12-14T18:31:55Z",
"modifiedBy": {
"email": "john.doe@smartsheet.com"
},
"modifiedAt": "2017-12-14T18:47:36Z",
"userCanModify": true,
"action": {
"type": "APPROVAL_REQUEST_ACTION",
"recipients": [
{
"email": "jane.roe@smartsheet.com"
}
],
"frequency": "WEEKLY",
"includeAllColumns": true,
"includeAttachments": true,
"includeDiscussions": true,
"notifyAllSharedUsers": false
}
}
PUT /sheets/{sheetId}/automationrules/{automationRuleId}
Updates an existing automation rule.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | An AutomationRule object. When sending an AutomationRule, you must always specify action.type and it must match the existing rule type. |
Returns | Result object containing the updated AutomationRule object |
Access Scope | WRITE_SHEETS |
Related Items
Disabled Reasons for Automation Rules
APPROVAL_COLUMN_MISSING | This rule's approval status column has been deleted. |
APPROVAL_COLUMN_WRONG_TYPE | The approval column must be a dropdown column. |
AUTOMATION_NOT_ENABLED_FOR_ORG | To create or edit automated actions, you need to upgrade your organization account to a Business or Enterprise plan. |
COLUMN_MISSING | A column referenced by this rule has been deleted. |
COLUMN_TYPE_INCOMPATIBLE | A column referenced by this rule has been changed to an incompatible column type. |
NO_POTENTIAL_RECIPIENTS | This rule has no recipients that will be able to receive notifications based on this sheet's permission settings or this account's approved domain sharing list. |
NO_VALID_SELECTED_COLUMNS | All selected columns for this rule have been deleted. |
Cells
A collection of cells comprises each row in a sheet.
Objects
Cell Object
Example: Cell object
{
"columnType": "TEXT_NUMBER",
"value": "Revision 1",
"displayValue": "Revision 1",
"columnId": 4583173393803140
}
columnId | number | The Id of the column that the cell is located in |
columnType | string | See type definition on the Column object. Only returned if the include query string parameter contains columnType. |
conditionalFormat | string | The format descriptor describing this cell's conditional format (see Formatting). Only returned if the include query string parameter contains format and this cell has a conditional format applied. |
displayValue | string | Visual representation of cell contents, as presented to the user in the UI. See Cell Reference. |
format | string | The format descriptor (see Formatting) Only returned if the include query string parameter contains format and this cell has a non-default format applied. |
formula | string | The formula for a cell, if set, for instance =COUNTM([Assigned To]3). NOTE: calculation errors or problems with a formula do not cause the API call to return an error code. Instead, the response contains the same value as in the UI, such as cell.value = "#CIRCULAR REFERENCE". |
hyperlink | Hyperlink | A hyperlink to a URL, sheet, or report |
image | Image | The image that the cell contains. Only returned if the cell contains an image. |
linkInFromCell | CellLink | An inbound link from a cell in another sheet. This cell's value mirrors the linked cell's value. |
linksOutToCells | CellLink[] | An array of CellLink objects. Zero or more outbound links from this cell to cells in other sheets whose values mirror this cell's value. |
objectValue | ObjectValue | Optionally included object representation of the cell's value. Used for updating predecessor cell values or for multi-contact details. |
overrideValidation | Boolean | (Admin only) Indicates whether the cell value can contain a value outside of the validation limits (value = true). When using this parameter, you must also set strict to false to bypass value type checking. This property is honored for POST or PUT actions that update rows. |
strict | Boolean | Set to false to enable lenient parsing. Defaults to true. You can specify this attribute in a request, but it is never present in a response. See Cell Value Parsing for more information about using this attribute. |
value | string, number, or Boolean |
A string, a number, or a Boolean value -- depending on the cell type and the data in the cell. Cell values larger than 4000 characters are silently truncated. An empty cell returns no value. See Cell Reference. |
Cell History Object
Extends the Cell object.
modifiedAt | timestamp | The datetime for when the change was made to the cell |
modifiedBy | User | User object containing the name and email of the user that made the change |
CellLink Object
Represents a link to a cell in a different sheet.
columnId | number | Column Id of the linked cell |
rowId | number | Row Id of the linked cell |
sheetId | number | Sheet Id of the sheet that the linked cell belongs to |
sheetName | string | Sheet name of the linked cell |
status | string | One of the following values:
|
Duration Object
Extends the ObjectValue object.
In a project sheet, represents a value in a duration cell, or a lag value of a predecessor.
objectType | string | DURATION |
days | number | The number of days for this duration. |
elapsed | Boolean | If true, indicates this duration represents elapsed time, which ignores non-working time. |
hours | number | The number of hours for this duration. |
milliseconds | number | The number of milliseconds for this duration. |
minutes | number | The number of minutes for this duration. |
negative | Boolean | When used as a predecessor's lag value, indicates whether the lag is negative (if true), or positive (false). The individual duration values themselves (for example, days, hours, or minutes) is always positive. |
seconds | number | The number of seconds for this duration. |
weeks | number | The number of weeks for this duration. |
Hyperlink Object
Represents a hyperlink to a dashboard, report, sheet, or URL.
reportId | number | If non-null, this hyperlink is a link to the report with this Id. |
sheetId | number | If non-null, this hyperlink is a link to the sheet with this Id. |
sightId | number | If non-null, this hyperlink is a link to the dashboard with this Id. |
url | string | When the hyperlink is a URL link, this property contains the URL value. When the hyperlink is a dashboard/report/sheet link (that is, sightId, reportId, or sheetId is non-null), this property contains the permalink to the dashboard, report, or sheet. |
ObjectValue Object
Example: ObjectValue object
{
"cells": [{
"columnId": 285878125913988,
"objectValue": {
"objectType": "MULTI_PICKLIST",
"values": ["hello", "world"]
}
}]
}
The base object for values found in the Cell.objectValue attribute. Its objectType attribute indicates the type of the object. This object itself is not used directly.
objectType | string | One of ABSTRACT_DATETIME, CONTACT, DATE, DATETIME, DURATION, MULTI_CONTACT, MULTI_PICKLIST, or PREDECESSOR_LIST |
Predecessor Object
rowId | number | The Id of the predecessor row |
type | string | The type of the predecessor. One of FF, FS, SF, or SS. |
inCriticalPath | Boolean | True if this predecessor is in the critical path. Read-only. |
invalid | Boolean | True if the row referenced by rowId is not a valid row in this sheet, or there is a circular reference (displayed in the Smartsheet app as "#REF"). Read-only. Omitted if false. |
lag | Duration | The lag value of this predecessor. Omitted if there is no lag. |
rowNumber | number | The row number of the predecessor row. Omitted if invalid is true. Read-only. |
PredecessorList Object
Example request: update row for a predecessor cell
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows?include=objectValue' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '[{"id": "6572427401553796", "cells": [{"columnId": 7518312134403972,"objectValue": {"objectType": "PREDECESSOR_LIST","predecessors": [{"rowId": 567735454328708,"type": "FS","lag": {"objectType": "DURATION","days": 2,"hours": 4}}]}}]}]'
// Not yet implemented
// Not yet implemented
// Not yet implemented
# Not yet implemented
# Not yet implemented
Example response
{
"message": "SUCCESS",
"result": [{
"id": 6572427401553796,
"rowNumber": 2,
"expanded": true,
"createdAt": "2015-01-09T11:41:55-08:00",
"modifiedAt": "2015-02-23T15:36:07-08:00",
"cells": [{
"columnId": 7518312134403972,
"value": "1FS +2d 4h",
"objectValue": {
"objectType": "PREDECESSOR_LIST",
"predecessors": [{
"rowId": 567735454328708,
"rowNumber": 1,
"type": "FS",
"lag": {
"objectType": "DURATION",
"days": 2,
"hours": 4
}
}]
},
"displayValue": "1FS +2d 4h"
}]
}]
}
Extends the ObjectValue object.
In a project sheet with dependencies enabled, the objectValue attribute for predecessor cells is an object of this type, which represents the predecessors for the row.
objectType | string | PREDECESSOR_LIST |
predecessors | Predecessor[] | Array of Predecessor objects. |
Get Cell History
Example request: get cell history
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history?include=columnType' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 9283173393803140,
rowId: 0123456789012345,
columnId: 4567890123456789
};
// Get cell history
smartsheet.sheets.getCellHistory(options)
.then(function(history) {
console.log(history);
})
.catch(function(error) {
console.log(error);
});
// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<CellHistory> results = smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(
9283173393803140, // sheetId
0123456789012345, // rowId
4567890123456789, // columnId
null, // IEnumerable<CellInclusion> includes
null // PaginationParameters
);
// Sample 2: Specify 'include' parameter with value of "COLUMN_TYPE" and 'includeAll' parameter with value of 'true'
PaginatedResult<CellHistory> results = smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(
9283173393803140, // sheetId
0123456789012345, // rowId
4567890123456789, // columnId
new CellInclusion[] { CellInclusion.COLUMN_TYPE },
new PaginationParameters(
true, // Boolean includeAll
null, // int pageSize
null) // int page
);
// Omit pagination
PagedResult<CellHistory> cellHistory = smartsheet.sheetResources().rowResources().cellResources().getCellHistory(
9283173393803140L, // long sheetId
0123456789012345L, // long rowId
4567890123456789L, // long columnId
null // PaginationParameters
);
# Sample 1: Get history
response = smartsheet_client.Cells.get_cell_history(
9283173393803140, # sheet_id
0123456789012345, # row_id
4567890123456789, # column_id
include_all=True)
revisions = response.data
# Sample 2: Paginate the list
response = smartsheet_client.Cells.get_cell_history(
9283173393803140, # sheet_id
0123456789012345, # row_id
4567890123456789, # column_id
page_size=5,
page=1)
pages = response.total_pages
revisions = response.data
response = smartsheet.sheets.cells.get_history(
sheet_id: 9283173393803140,
row_id: 0123456789012345,
column_id: 4567890123456789
)
revisions = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 3,
"data": [
{
"columnId":4567890123456789,
"displayValue": "Revision 3",
"columnType": "TEXT_NUMBER",
"value": "Revision 3",
"modifiedAt": "2013-06-24T00:10:18Z",
"modifiedBy" : {
"name" : "Jane Smart",
"email" : "jane.smart@smartsheet.com"
}
},
{
"columnId":4567890123456789,
"displayValue": "Revision 2",
"columnType": "TEXT_NUMBER",
"value": "Revision 2",
"modifiedAt": "2013-06-23T00:10:18Z",
"modifiedBy" : {
"name" : "Joe Smart",
"email" : "joe.smart@smartsheet.com"
}
},
{
"columnId":4567890123456789,
"displayValue": "Revision 1",
"columnType": "TEXT_NUMBER",
"value": "Revision 1",
"modifiedAt": "2013-06-22T00:10:18Z",
"modifiedBy" : {
"name" : "Joe Smart",
"email" : "joe.smart@smartsheet.com"
}
}
]
}
GET /sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history
Gets the cell modification history.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | include (optional) -- comma-separated list of elements to copy:
|
level (optional): specifies whether multi-contact data is returned in a backwards-compatible, text format (level=0, default) or as multi-contact data (level=1). | |
This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. | |
Returns | IndexResult object containing an array of Cell History objects. For more details, see Cell Reference. |
Access Scope | READ_SHEETS |
Update Cells
To update the cells in a sheet, use the Update Rows operation.
Related Items
Cell Links
Creating or updating cell links via the cell.linkInFromCell attribute is a special operation. A given row or cell update operation may contain only link updates, or no link updates. Attempting to mix row/cell updates with cell link updates results in error code 1115. Additionally, a CellLink object can only be added to an existing cell, so the cell.linkInFromCell attribute is not allowed when POSTing a new row to a sheet.
When creating a cell link, cell.value must be null (the data is pulled from the linked cell).
A cell may not contain both a hyperlink and a cell link, so hyperlink and linkInFromCell may never both be non-null at the same time.
Cell Reference
Cell Value Representation
Cell objects retrieved through the Smartsheet APIs have two main attributes representing cell values: Cell.value, and Cell.displayValue. A third attribute, Cell.objectValue is currently used only for adding and updating predecessors, or for multi-contact or multi-picklist details, such as email addresses or values in a multi-picklist. An empty cell returns no value.
Cell.displayValue is always a string and is only returned for certain column types (see below). It represents the formatted value as it should be displayed to an end-user. For example, if a TEXT_NUMBER column is formatted as a US Dollar currency, its value may be a number like 1234.5678, but its displayValue is "$1,234.57".
Cell.value represents a cell's raw value and can be one of the following primitive JSON types: string, number, or Boolean, depending on the column type. An empty cell returns no value. Complex types are represented as strings, formatted as described below:
Column Type | Possible Types for Cell.value | Returns Cell.displayValue? |
---|---|---|
ABSTRACT_DATETIME | string: a project date and time in ISO-8601 format, or a free-form text value. number: see Dates and Times for how to request dates to be returned as numbers. |
No. |
CHECKBOX | Boolean: true if the checkbox is checked, false if unchecked, no value if the cell hasn't been touched yet. string: a free-form text value. |
No. |
CONTACT_LIST | string: an email address representing a contact, or a free-form text value. | Yes: same as value for free-form strings; for contacts, the contact's name if any, else their email address. |
DATE | string: a date in ISO-8601 format, or a free-form text value. number: see Dates and Times for how to request dates to be returned as numbers. |
No. |
DURATION | string: a duration value such as "4d 6h 30m" in the user's locale, or a free-form text value. See the Help Center for more information on durations. |
Yes: same as value |
MULTI_CONTACT_LIST | string: only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying, otherwise the column type is TEXT_NUMBER. | Yes: same as value; to see actual email addresses, see below. |
MULTI_PICKLIST | string: only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying, otherwise the column type is TEXT_NUMBER. | Yes: same as value; to see objectValue, see below. |
PICKLIST | string: one of the picklist's column options, or a free-form text value. number: numeric values |
Yes: same as value for strings; for number values, the number with formatting applied. |
PREDECESSOR | string: a comma-delimited predecessor list such as "12FS +3d 4h, 14SS", or a free-form text value. See the Help Center for more information on predecessors. |
Yes: same as value |
TEXT_NUMBER | string: free-form text values number: numeric values |
Yes: same as value for strings; for number values, the number with formatting applied. |
Cell.objectValue is an object representation of a cell's value and is currently used for adding or updating predecessor cell values, or for multi-contact details, such as email addresses.
- For predecessors, it provides a more "programmer friendly" format for assembling predecessors. To update a cell's predecessors, set objectValue to a PredecessorList object containing Predecessor objects.
- For multi-contact or multi-picklist details, use both a level query parameter and an include=objectValue query to see email addresses rather than display names or to see multi-picklist values.
Cell Value Parsing
The flexibility in cell value data types is a powerful feature in the Smartsheet application; however, it poses a challenge for an API in terms of parsing. Being too flexible might result in unexpected behavior. For instance, if you write code to post a Date value to a Smartsheet and the API operation succeeds, you might assume that the date value you sent was interpreted as date. What happens if you posted your date in the wrong format? Do you really want Smartsheet to keep the malformed date as a string value? Probably not.
To address this problem, the Smartsheet API employs a simple scheme to indicate whether you want a more predictable and strict interface or a more flexible one. By default, a cell value is expected to conform to "strict" rules for the type of the cell's column. If an input value doesn't conform, the API returns error code 1042.
If, however, you want the same flexibility as the Smartsheet Web app, you can disable the strict rules, and we’ll do our best to make sense of it. To enable lenient parsing simply include "strict": false in the Cell object in your request body.
The parsing rules for the various column types are as follows:
ABSTRACT_DATETIME
lenient | Smartsheet attempts to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, Smartsheet recognizes the date and stores it as such. All other values are simply text values. |
strict | The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of numericDates set to true to have Smartsheet convert epoch time to human readable dates. See Dates and Times for more information. |
CHECKBOX
lenient | Boolean values and string values of true and false are handled the same as strict. All other values are saved as text values. |
strict | Only Boolean values (true or false) are valid. |
CONTACT_LIST
lenient | If the value is a valid email address, Smartsheet handles it the same as strict. If not, Smartsheet saves the value as a text value. |
strict | The value must be a valid email address. If displayValue is set, Smartsheet uses that as the name; otherwise, if Smartsheet finds a match among the the access token owner's contacts, Smartsheet associates this cell with that existing contact. |
DATE
lenient | Smartsheet attempts to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, Smartsheet recognizes the date and stores it as such. All other values are simply text values. |
strict | The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of numericDates set to true to have Smartsheet convert epoch time to human readable dates. See Dates and Times for more information. |
DURATION
lenient | Numeric values are treated as duration values in days. String values which are valid duration strings in the user's locale are treated as durations, and any other values are treated as free-form text values. |
strict | Only valid duration strings in the user's locale are valid. Information on duration strings can be found in Help Center. |
MULTI_CONTACT_LIST
N/A | Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference. |
MULTI_PICKLIST
N/A | Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference. |
PICKLIST
lenient | All numeric and text values are valid. Formatted numbers are parsed like TEXT_NUMBER formatted numbers. |
strict | The value must be a string and must be one of the options for the picklist. |
PREDECESSOR
N/A | Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference. |
TEXT_NUMBER
lenient | All numeric and text values are valid. Formatted numbers passed as text values, such as currencies ("$5,000"), percentages ("50%"), or decimals ("100.5") are parsed to their numeric equivalents, based on the locale of the access token owner, with the proper formatting enabled for the cell. |
strict | All numeric and text values are valid and are interpreted literally. |
Contact List Columns
With columns of type CONTACT_LIST, the cell attributes value and displayValue are treated independently. The contact’s email address is represented by value, while the contact’s name (and the value displayed in the cell in the Smartsheet app) is represented by displayValue.
When creating or updating cells for a contact list column, the displayValue attribute works as follows:
- If displayValue is non-null and non-empty, the Smartsheet cell displays the value provided.
- If displayValue is an empty string, the Smartsheet cell displays the email address.
- If displayValue is null or absent, Smartsheet makes a best guess effort at filling it in with a contact’s name based on the email address.
Hyperlinks
You can create and modify hyperlinks by using any API operation that creates or updates cell data. When creating or updating a hyperlink, cell.value may be set to a string value or null. If null, the cell's value is derived from the hyperlink:
- If the hyperlink is a URL link, the cell's value is set to the URL itself.
- If the hyperlink is a dashboard, report, or sheet link, the cell's value is set to the dashboard, report, or sheet name.
Images in Cells
For details about working with images in cells, see Cell Images.
Cell Images
A cell image is an image that has been uploaded to a cell within a sheet.
Objects
Image Object
id | string | Image Id |
altText | string | Alternate text for the image |
height | number | Original height (in pixels) of the uploaded image |
width | number | Original width (in pixels) of the uploaded image |
ImageUrl Object
Example: ImageUrl object
{
"imageId": "e1znCxhuZo_soEJtUmmX_A",
"url": "https://urltoimage1.com?qs1=foo"
}
imageId | string | Image Id |
error | Error object | Present in the Get All Image URLs response only if an error occurred retrieving the image. |
height | number | Image height (in pixels). In the Get All Image URLs request, this (optional) attribute represents requested height; in the response, it represents actual height of the image returned. (See List Image URLs.) |
url | string | Temporary URL that can be used to retrieve the image. This attribute can be present in a response but is never specified in a request. |
width | number | Image width (in pixels). In the Get All Image URLs request, this (optional) attribute represents requested width; in the response, it represents actual width of the image returned. (See List Image URLs.) |
ImageUrlMap Object
imageUrls | ImageUrl[] | Array of ImageUrl objects |
urlExpiresInMillis | number | Milliseconds before the URLs within imageUrls expire |
Add Image to Cell
Example request: add image to cell
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages?altText=my%20image' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: image/jpeg" \
-H 'Content-Disposition: attachment; filename="picture.jpg"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @picture.jpg
// Enable FileStream
var fs = require("fs")
// Set options
var options = {
sheetId: 1696831624483716,
rowId: 1049441315358596,
columnId: 74761903175665540,
fileSize: 458, // Must be exact bytes; no rounding
fileName: "img_pl_decisionshapesHold.png",
fileStream: fs.createReadStream("/Users/jroe/Documents/images/img_pl_decisionshapesHold.png"),
queryParameters: {
"altText": "Caution sign",
"overrideValidation": true
}
};
// Add image to cell
smartsheet.sheets.addImageToCell(options)
.then(function(image) {
console.log(image);
})
.catch(function(error) {
console.log(error);
});
// Set options
Image image = new Image
{
AltText = "Caution Sign",
Height = 16,
Width = 16
};
smartsheet.SheetResources.RowResources.CellResources.AddImageToCell(
1696831624483716, // sheetId
1049441315358596, // rowId
74761903175665540, // columnId
"/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png",
"image"
);
// Set options
Image image = new Image()
.setAltText("Caution sign")
.setHeight(16L)
.setWidth(16L);
smartsheet.sheetResources().rowResources().cellResources().addImageToCell(
1639534409607044L, // sheetId
1049441315358596L, // rowId
74761903175665540L, // columnId
"/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png",
"image"
);
sheet_id = 1696831624483716
column_id = 74761903175665540
row_id = 1049441315358596
caution_pic = "/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png"
file_type = "png"
smartsheet_client.Cells.add_image_to_cell(sheet_id, row_id, column_id, caution_pic, file_type)
# Sample 1: Add image from path
response = smartsheet.sheets.cells.add_image_from_path(
sheet_id: 1696831624483716,
row_id: 1049441315358596,
column_id: 74761903175665540,
path: '/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png'
)
new_image = response[:result]
# Sample 2: Add image
filename = '/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png'
file = File.open(filename)
file_length = File.size(filename)
response = smartsheet.sheets.cells.add_image(
sheet_id: 1696831624483716,
row_id: 1049441315358596,
column_id: 74761903175665540,
file: file,
filename: filename,
file_length: file_length
)
new_image = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": [{
"id": 6039340093597572,
"rowNumber": 6,
"siblingId": 1535740466227076,
"expanded": true,
"createdAt": "2017-08-28T21:29:16Z",
"modifiedAt": "2017-08-30T08:10:47Z",
"cells": []
}],
"version": 19
}
POST /sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages
Uploads an image to the specified cell within a sheet.
Headers | See Simple Uploads for information about required headers. |
Parameters | altText (optional): url-encoded alternate text for the image overrideValidation (optional): You may use the query string parameter overrideValidation with a value of true to allow a cell value outside of the validation limits. You must specify strict with a value of false to bypass value type checking. |
Request Body | Binary content for the file |
Returns | Result object |
Access Scope | WRITE_SHEETS |
Download Cell Image
Example request: download cell image
// Steps 1 and 2: Locate the cell and obtain the imageId
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
// In the response, note the columnId and ImageId
// You might also save the altText for Step 4
{
"cells": [{
"columnId": 6800865311909764,
"image": {
"id": "nQCn-Bm2ncwqsw_FX1XI_w",
"height": 932,
"width": 1562,
"altText": "stanley hotel.png"
}
}]
}
// Step 3: Obtain a temporary image URL
curl https://api.smartsheet.com/2.0/imageurls \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"imageId": "nQCn-Bm2ncwqsw_FX1XI_w","height":40,"width": 20}]'
// In the response, note the URL and its expiration time
{
"urlExpiresInMillis": 1800000,
"imageUrls": [
{
"imageId": "nQCn-Bm2ncwqsw_FX1XI_w",
"url": "https://aws.smartsheet.com/storageProxy/image/images/OMB9hAConFbhUdJMQ5czQEkwAj1-ErW-sXz3Dr4nDfE?expirationDate=2017-07-25T22%3A13%3A07%2B0000&height=40&width=20&hmac=e%2BfIb0ffUK%2BZeA2hbGx%2Fj8YcWUY%3D"
}
]
}
// Step 4: Download the image
curl -o "stanley_hotel.png" "https://aws.smartsheet.com/storageProxy/image/images/OMB9hAConFbhUdJMQ5czQEkwAj1-ErW-sXz3Dr4nDfE?expirationDate=2017-07-25T22%3A01%3A33%2B0000&height=40&width=20&hmac=5t%2FHs9%2BXTk5cNhyDax9ZgcbepKI%3D"
var fs = require('fs');
var request = require('request');
var sheetId = 1639534409607044;
var rowId = 3344087179913092;
var columnId = 1735559124150148;
// Step 1: Identify the cell that contains an image
smartsheet.sheets.getRow({
sheetId: sheetId,
rowId: rowId
}).then(row => {
var cell = row.cells.find(cell => cell.columnId === columnId);
// Step 2: Get image info from cell
var image = cell.image;
var imageId = image.id;
var localFileName = image.altText;
// Step 3: Build list of image URLs
smartsheet.images.listImageUrls({
body: [{imageId: imageId}]
}).then(result => {
var imageUrl = result.imageUrls[0].url;
// Step 4: Download the image
request(imageUrl).pipe(fs.createWriteStream(localFileName));
});
});
sheetId = 1639534409607044;
rowId = 3344087179913092;
columnId = 1735559124150148;
// Step 1: Identify the cell that contains an image
Row row = smartsheet.SheetResources.RowResources.GetRow(
sheetId,
rowId,
null,
null);
Cell cell = row.Cells.First(c => c.ColumnId == columnId);
// Step 2: Get image info from cell
Image image = cell.Image;
string imageId = image.Id;
string localFileName = image.AltText;
// Step 3: Build list of image urls
ImageUrl[] imageUrls = new ImageUrl[] { new ImageUrl { ImageId = imageId } };
string temporaryUrl = smartsheet.ImageUrlResources.GetImageUrls(imageUrls).ImageUrls[0].Url;
// Step 4: Download the image
System.Net.WebClient client = new System.Net.WebClient();
client.DownloadFile(temporaryUrl, localFileName);
long sheetId = 5670346721388420L;
long rowId = 3344087179913092L;
long columnId = 1735559124150148L;
// Step 1: Identify the cell that contains an image
Row row = smartsheet.sheetResources().rowResources().getRow(
sheetId,
rowId,
null,
null);
Cell cell = row.getCells().stream().filter(c -> c.getColumnId() == columnId).findFirst().orElse(null);
// Step 2: Get image info from cell
Image image = cell.getImage();
String imageId = image.getId();
String localFileName = image.getAltText();
// Step 3: Build list of image urls
ImageUrl imageUrl = new ImageUrl();
imageUrl.setImageId(imageId);
List<ImageUrl> imageUrls = Arrays.asList(imageUrl);
String temporaryUrl = smartsheet.imageUrlResources().getImageUrls(imageUrls).getImageUrls().get(0).getUrl();
// Step 4: Download the image
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpget = new HttpGet(temporaryUrl);
CloseableHttpResponse response = httpclient.execute(httpget);
HttpEntity entity = response.getEntity();
FileOutputStream fos = new FileOutputStream(localFileName);
entity.writeTo(fos);
fos.close();
sheetId = 1639534409607044
rowId = 3344087179913092
columnId = 1735559124150148
# Steps 1 and 2: Locate the cell and obtain the imageId
row = smartsheet_client.Sheets.get_row(sheet_id, row_id)
cell = row.get_column(column_id)
image = cell.image
image_id = image.id
# Automate using Alt Text as the file name
filename = getattr(image, 'alt_text', default_filename)
# Step 3: Obtain a temporary image URL
imageUrl = smartsheet.models.ImageUrl( { "imageId": image_id } )
response = smartsheet_client.Images.get_image_urls([imageUrl])
url = response.image_urls[0].url
# Step 4: Download the image
import requests
response = requests.get(url)
if response.status_code == 200:
with open(filename, 'wb') as f:
f.write(response.content)
require 'open-uri'
sheet_id = 1639534409607044
row_id = 3344087179913092
column_id = 1735559124150148
default_filename = 'my_image.png'
# Steps 1 and 2: Locate the cell and obtain the imageId
row = smartsheet.sheets.rows.get(sheet_id: sheet_id, row_id: row_id)
cell = row[:cells].select { |cell| cell[:column_id] == column_id }.first
image = cell[:image]
image_id = image[:id]
# Automate using Alt Text as the file name
filename = image[:alt_text] || default_filename
# Step 3: Obtain a temporary image URL
response = smartsheet.sheets.list_image_urls(body: [{image_id: image_id}])
url = response[:image_urls][0][:url]
# Step 4: Download the image
image_download = open(url)
IO.copy_stream(image_download, filename)
Downloading a cell image is a multi-step process. This sample downloads a cell image to a local file. The cell is specified by sheet Id, row Id, and column Id.
Click the appropriate language tab in the rightmost pane to see sample code.
Step 1. Locate the cell
Get the desired row, then locate the desired cell based on the column Id.
Step 2. Obtain the image Id
Cell images are identified by an image Id, which is stored in a cell Image object. (The image Id is the key to the image and should be kept secure.)
When a user uploads an image to a cell, Smartsheet uses the original file name as the image "alt text." This example uses that alt text value as the local file name.
Step 3. Obtain a temporary image URL
The POST /imageurls
command creates a temporary URL that you can use to download the image. The URL expires after a short time, which is reported in the response.
Step 4. Download the image
Once you have the URL, issue a standard HTTP GET to download the image and save as a local file.
List Image URLs
Example request: list image URLs
curl https://api.smartsheet.com/2.0/imageurls \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"imageId": "e1znCxhuZo_soEJtUmmX_A","height":40,"width": 20},{"imageId": "g2jdKdfhQa_abKJmPnhC_B","height":100,"width": 50}]'
// Set options
var options = {
body: [{
imageId: "jpbGklqdfZuL4Jw-kZhdZA",
width: 256,
height: 256
}]
};
// List image URLs
smartsheet.images.listImageUrls(options)
.then(function(temporaryUrls) {
console.log(temporaryUrls);
})
.catch(function(error) {
console.log(error);
});
// Build list of image urls
ImageUrl[] imageUrls = new ImageUrl[] { new ImageUrl { ImageId = "jpbGklqdfZuL4Jw-kZhdZA" } };
string temporaryUrl = smartsheet.ImageUrlResources.GetImageUrls(imageUrls).ImageUrls[0].Url;
// Build list of image urls
ImageUrl imageUrl = new ImageUrl()
.setImageId("jpbGklqdfZuL4Jw-kZhdZA");
List<ImageUrl> imageUrls = Arrays.asList(imageUrl);
String temporaryUrl = smartsheet.imageUrlResources().getImageUrls(imageUrls).getImageUrls().get(0).getUrl();
imageUrl = smartsheet.models.ImageUrl(
{
"imageId": 'jpbGklqdfZuL4Jw-kZhdZA',
"height": 256,
"width": 256
}
)
response = smartsheet_client.Images.get_image_urls([imageUrl])
url = response.image_urls[0].url
body = [
{
image_id: 'jpbGklqdfZuL4Jw-kZhdZA',
height: 100,
width: 100
}
]
image_urls = smartsheet.sheets.list_image_urls(
body: body
)
Example response
{
"urlExpiresInMillis": 1800000,
"imageUrls": [{
"imageId": "jpbGklqdfZuL4Jw-kZhdZA",
"url": "https://urltoimage1.com?qs1=foo"
},
{
"imageId": "g2jdKdfhQa_abKJmPnhC_B",
"error": {
"errorCode": 5001,
"message": "You do not have permission to view this image."
}}]
}
POST /imageurls
Gets a list of URLs that can be used to retrieve the specified cell images.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Array of ImageUrl objects, with the following attributes:
|
Returns | ImageUrlMap object |
Access Scope | READ_SHEETS |
To retrieve images, see the workflow in Download Cell Image.
Remove Image from Cell
To remove an image from a cell (and set cell contents to either empty or to another value), use the Update Rows operation to set cell.value to the new value.
Update Cell Image
A cell image can be updated as follows:
- To change the alternate text of an image, use the Update Rows operation.
- To replace an existing image with a new image, use the Add Image to Cell operation.
- To add an image to a cell that previously contained another type of data, use the Add Image to Cell operation.
Columns
A column is a component of a sheet or report.
Objects
Column Object
Example: Column object
{
"id": 7960873114331012,
"version": 2,
"index": 4,
"title": "Interesting Choices",
"formula": "=data@row",
"type": "MULTI_PICKLIST",
"options": [
"1",
"Hello, World",
"100%"
],
"validation": false,
"width": 150
}
id | number | Column Id |
systemColumnType | string | When applicable, one of: AUTO_NUMBER, CREATED_BY, CREATED_DATE, MODIFIED_BY, MODIFIED_DATE. See System Columns. |
type | string | One of:
|
autoNumberFormat | AutoNumberFormat | Present when systemColumnType == AUTO_NUMBER |
contactOptions | ContactOption[] | Array of ContactOption objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST |
description | string | Column description. |
format | string | The format descriptor (see Formatting) Only returned if the include query string parameter contains format and this column has a non-default format applied to it. |
formula | string | The formula for a column, if set, for instance =data@row. |
hidden | Boolean | Indicates whether the column is hidden |
index | number | Column index or position. This number is zero-based. |
locked | Boolean | Indicates whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin. |
lockedForUser | Boolean | Indicates whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request. |
options | string[] | Array of the options available for the column |
primary | Boolean | Returned only if the column is the Primary Column (value = true) |
symbol | string | When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns. |
tags | string[] | Set of tags to indicate special columns. Each element in the array is set to one of the following values:
|
title | string | Column title |
validation | Boolean | Indicates whether validation has been enabled for the column (value = true) |
version | number | Read only. The level of the column type. Each element in the array is set to one of the following values:
|
width | number | Display width of the column in pixels |
ContactOption Object
string | A parsable email address. | |
name | string | Can be a user's name, display name, or free text, such as a job class or TBD. |
Add Columns
Example request: add columns
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"title": "New Multi-Picklist Column 1", "type": "MULTI_PICKLIST", "options": ["First", "Second", "Third"], "index": 4} , {"title":"New Date Column", "type":"DATE", "formula": "=data@row", "validation":"true", "index":4},]'
-d '[{"index": 6, "title": "Dropdown Multi Select", "type": "MULTI_PICKLIST", "options": ["Template", "Blog", "Newsletter", "Email", "Press Release", "Advertisement"], "validation": false, "width": 150}]'
// Specify new columns
var column = [
{
"title": "New Picklist Column 1",
"type": "PICKLIST",
"options": [
"First",
"Second",
"Third"
],
"index": 4
},
{
"title": "New Date Column",
"type": "DATE",
"formula": "=data@row",
"validation": true,
"index": 4
}
];
// Set options
var options = {
sheetId: 2252168947361668,
body: column
};
// Add columns to the sheet
smartsheet.sheets.addColumn(options)
.then(function(newColumns) {
console.log(newColumns);
})
.catch(function(error) {
console.log(error);
});
// Create a column
Column columnA = new Column
{
Title = "This is a new multi-picklist column",
Index = 0,
Type = ColumnType.MULTI_PICKLIST,
Options = new string[] { "Cat", "Rat", "Bat" }
};
// Create another column
Column columnB = new Column
{
Title = "New Date Column",
Formula = "=data@row",
Index = 4,
Type = ColumnType.DATE
};
// Add columns to the sheet
IList<Column> addedColumns = smartsheet.SheetResources.ColumnResources.AddColumns(
2252168947361668, // sheet Id
new Column[] { columnA, columnB }
);
// Create columns
Column column1 = new Column()
.setTitle("New Multi-Picklist Column 1")
.setType(ColumnType.MULTI_PICKLIST)
.setIndex(4)
.setOptions(Arrays.asList("First", "Second", "Third"));
Column column2 = new Column()
.setTitle("New Date Column")
.setType(ColumnType.DATE)
.setFormula("=data@row")
.setValidation(true)
.setIndex(4);
// Add columns to the sheet
List<Column> newColumns = smartsheet.sheetResources().columnResources().addColumns(
2252168947361668L, // long sheetId
Arrays.asList(column1, column2)
);
# Create the columns
column1 = smartsheet.models.Column({
'title': 'New Picklist Column 1',
'type': 'PICKLIST',
'options': [
'First',
'Second',
'Third'
],
'index': 4
})
column2 = smartsheet.models.Column({
'title': 'New Date Column',
'type': 'DATE',
'formula': '=data@row',
'validation': 'True',
'index': 4
})
# Add columns to the sheet
new_columns = smartsheet_client.Sheets.add_columns(
2252168947361668, # sheet_id
[column1, column2])
# Define options
body = {
title: 'New Picklist Column 1',
type: 'PICKLIST',
options: [
'First',
'Second',
'Third'
],
index: 4
},
{
title: "New Date Column",
type: 'DATE',
formula: 'data@row',
validation: true,
index: 4
}
# Add the column
new_columns = smartsheet.sheets.columns.add(
sheet_id: 2252168947361668,
body: body
)
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": [
{
"id": 9007194052434043,
"index": 4,
"title": "New Picklist Column 1",
"type": "PICKLIST",
"options": [
"First",
"Second",
"Third"
],
"validation": false,
"width": 150
},
{
"id": 4503594425063547,
"index": 4,
"title": "New Date Column",
"formula": "=data@row",
"type": "DATE",
"validation": true,
"width": 150
}
]
}
POST /sheets/{sheetId}/columns
Inserts one or more columns into the sheet specified in the URL. This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Column object or an array of Column objects, with the following attributes:
|
Returns | Result object containing the newly created columns -- either a single Column object or an array of Column objects, corresponding to what was specified in the request. |
Access Scope | ADMIN_SHEETS |
Delete Column
Example request: delete column
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
sheetId: 9283173393803140,
columnId: 0123456789012345
};
// Delete column
smartsheet.sheets.deleteColumn(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.SheetResources.ColumnResources.DeleteColumn(
9283173393803140, // sheetId
0123456789012345 // columnId
);
smartsheet.sheetResources().columnResources().deleteColumn(
9283173393803140L, // long sheetId
0123456789012345L // long columnId
);
smartsheet_client.Sheets.delete_column(
9283173393803140, # sheet_id
0123456789012345) # column_id
smartsheet.sheets.columns.delete(
sheet_id: 9283173393803140,
column_id: 0123456789012345
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /sheets/{sheetId}/columns/{columnId}
Deletes the column specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | ADMIN_SHEETS |
Get Column
Example request: get column
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 9283173393803140,
columnId: 7960873114331012
};
// Get column
smartsheet.sheets.getColumns(options)
.then(function(column) {
console.log(column);
})
.catch(function(error) {
console.log(error);
});
// Sample 1: Omit 'include' parameter
Column column = smartsheet.SheetResources.ColumnResources.GetColumn(
9283173393803140, // sheetId
7960873114331012, // columnId
null // IEnumerable<ColumnInclusion> includes
);
// Sample 2: Specify 'include' parameter with value of "FILTERS"
Column column = smartsheet.SheetResources.ColumnResources.GetColumn(
9283173393803140, // sheetId
7960873114331012, // columnId
new ColumnInclusion[] { ColumnInclusion.FILTERS }
);
// Sample 1: Omit 'include' parameter
Column column = smartsheet.sheetResources().columnResources().getColumn(
9283173393803140L, // long sheetId
7960873114331012L, // long columnId
null // EnumSet<ColumnInclusion> includes
);
// Sample 2: Specify 'include' parameter with value of "FILTERS"
Column column = smartsheet.sheetResources().columnResources().getColumn(
9283173393803140L, // long sheetId
7960873114331012L, // long columnId
EnumSet.of(ColumnInclusion.FILTERS)
);
column = smartsheet_client.Sheets.get_column(
9283173393803140, # sheet_id
7960873114331012) # column_id
column = smartsheet.sheets.columns.get(
sheet_id: 9283173393803140,
column_id: 7960873114331012
)
Example response
{
"id": 7960873114331012,
"index": 2,
"symbol": "STAR",
"title": "Favorite",
"type": "CHECKBOX",
"validation": false
}
GET /sheets/{sheetId}/columns/{columnId}
Gets the column specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | level (optional): specifies whether new functionality, such as multi-contact data is returned in a backwards-compatible, text format (level=0, default), multi-contact data (level=1), or multi-picklist data (level=2). |
Returns | Column object |
Access Scope | READ_SHEETS |
List Columns
Example request: list columns
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 9283173393803140
};
// List columns
smartsheet.sheets.getColumns(options)
.then(function(columnList) {
console.log(columnList);
})
.catch(function(error) {
console.log(error);
});
// Omit 'include' parameter and pagination parameters
PaginatedResult<Column> columns = smartsheet.SheetResources.ColumnResources.ListColumns(
9283173393803140, // sheetId
null, // IEnumerable<ColumnInclusion> include
null, // PaginationParameters
2 // int compatibilityLevel
);
// Omit 'include' parameter and pagination parameters
PagedResult<Column> columns = smartsheet.sheetResources().columnResources().listColumns(
9283173393803140L, // long sheetId
null, // EnumSet<ColumnInclusion> includes
null // PaginationParameters
);
response = smartsheet_client.Sheets.get_columns(
9283173393803140, # sheet_id
include_all=True)
columns = response.data
response = smartsheet.sheets.columns.list(
sheet_id: 9283173393803140
)
columns = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 3,
"data": [
{
"id": 7960873114331012,
"index": 0,
"symbol": "STAR",
"title": "Favorite",
"type": "CHECKBOX",
"validation": false
},
{
"id": 642523719853956,
"index": 1,
"primary": true,
"title": "Primary Column",
"type": "TEXT_NUMBER",
"validation": false
},
{
"id": 5146123347224452,
"index": 2,
"title": "Status",
"type": "PICKLIST",
"validation": false
}
]
}
GET /sheets/{sheetId}/columns
Gets a list of all columns belonging to the sheet specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. |
level (optional): specifies whether multi-contact data is returned in a backwards-compatible, text format (level=0, default) or as multi-contact data (level=1). | |
Returns | IndexResult object containing an array of Column objects |
Access Scope | READ_SHEETS |
Update Column
Example request: update column
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X PUT \
-d '{"title": "New multi-select dropdown column", "index": 0, "type": "MULTI_PICKLIST", "options": ["One", "Two"]}'
// Specify column properties
var column = {
"index": 0,
"title": "First Column",
"type": "PICKLIST",
"options": ["One", "Two"]
};
// Set options
var options = {
sheetId: 2252168947361668,
columnId: 5005385858869124,
body: column
};
// Update column
smartsheet.sheets.updateColumn(options)
.then(function(updatedColumn) {
console.log(updatedColumn);
})
.catch(function(error) {
console.log(error);
});
// Specify column properties
Column columnSpecification = new Column
{
Id = 5005385858869124,
Title = "First Column",
Index = 0,
Type = ColumnType.PICKLIST,
Options = new string[] { "One", "Two"}
};
// Update column
Column updatedColumn = smartsheet.SheetResources.ColumnResources.UpdateColumn(
2252168947361668, // sheetId
columnSpecification
);
// Specify column properties
Column columnSpecification = new Column(5005385858869124L)
.setTitle("First Column")
.setIndex(0)
.setType(ColumnType.PICKLIST)
.setOptions(Arrays.asList("One", "Two"));
// Update column
Column updatedColumn = smartsheet.sheetResources().columnResources().updateColumn(
2252168947361668L, // sheetId
columnSpecification
);
# Specify column properties
column_spec = smartsheet.models.Column({
'title': 'First Column',
'type': 'PICKLIST',
'options': ["One", "Two"],
'index': 0
})
# Update column
response = smartsheet_client.Sheets.update_column(
2252168947361668, # sheet_id
5005385858869124, # column_id
column_spec)
updated_column = response.result
# Specify column properties
body = {
title: 'First Column',
type: 'PICKLIST',
options: [
'One',
'Two'
]
}
# Update column
response = smartsheet.sheets.columns.update(
sheet_id: 2252168947361668,
column_id: 5005385858869124,
body: body
)
updated_column = response[:result]
Example response
{
"message": "SUCCESS",
"result": {
"id": 5005385858869124,
"index": 0,
"options" : ["One", "Two"],
"title": "First Column",
"type": "PICKLIST",
"validation": false
},
"resultCode": 0
}
PUT /sheets/{sheetId}/columns/{columnId}
Updates properties of the column, moves the column, and/or renames the column.
NOTES:
- You cannot change the type of a Primary column.
- While dependencies are enabled on a sheet, you can't change the type of any special calendar/Gantt columns.
- If the column type is changed, all cells in the column are converted to the new column type and column validation is cleared.
Type is optional when moving or renaming, but required when changing type or dropdown values.
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/jsonRequest Body A Column object that contains the following attributes: - index
- autoNumberFormat (optional)
- contactOptions (optional) -- must have set column type to CONTACT_LIST
- description (optional)
- format (optional)
- formula (optional)
- hidden (optional)
- locked (optional)
- options (optional)
- symbol (optional)
- systemColumnType (optional)
- title (optional)
- type (optional)
- validation (optional)
- width (optional)
Returns Result object containing the Column object that was modified Access Scope ADMIN_SHEETS
Related Items
Column Types
Example column types
{
"columns": [{
"id": 9999137079650180,
"version": 0,
"index": 0,
"title": "Text/Number",
"type": "TEXT_NUMBER",
"primary": true,
"validation": false,
"width": 150
},
{
"id": 9999736707020676,
"version": 0,
"index": 1,
"title": "Contact Column",
"type": "CONTACT_LIST",
"contactOptions": [{
"name": "ziggy@example.com",
"email": "ziggy@example.com"
}],
"validation": false,
"width": 150
},
{
"id": 999962382411652,
"version": 1,
"index": 2,
"title": "Multi Contact Column",
"type": "MULTI_CONTACT_LIST",
"contactOptions": [{
"name": "Ziggy Star",
"email": "ziggy@example.com"
},
{
"name": "Jane Roe",
"email": "jane.roe@example.com"
}
],
"validation": false,
"width": 185
},
{
"id": 9999562009782148,
"version": 0,
"index": 3,
"title": "Date Column",
"type": "DATE",
"validation": false,
"width": 150
},
{
"id": 9999762196096900,
"version": 0,
"index": 4,
"title": "Dropdown Single Select",
"type": "PICKLIST",
"options": [
"Project",
"Story",
"Task",
"Spike",
"Bug"
],
"validation": false,
"width": 150
},
{
"id": 9999361823467396,
"version": 2,
"index": 5,
"title": "Dropdown Multi Select",
"type": "MULTI_PICKLIST",
"options": [
"Template",
"Blog",
"Newsletter",
"Email",
"Press Release",
"Advertisement"
],
"validation": false,
"width": 150
},
{
"id": 9999104171726724,
"version": 0,
"index": 6,
"title": "Checkbox",
"type": "CHECKBOX",
"validation": false,
"width": 150
},
{
"id": 9999504544356228,
"version": 0,
"index": 7,
"title": "Symbols",
"type": "PICKLIST",
"symbol": "PAIN",
"options": [
"No Pain",
"Mild",
"Moderate",
"Severe",
"Very Severe",
"Extreme"
],
"validation": false,
"width": 150
}]}
Smartsheet supports the following standard column types, which are represented in a Column object with a type attribute set to one of the following:
Column Type | Column.type Value | Notes |
---|---|---|
Checkbox | CHECKBOX | Checkbox, star, and flag types |
Contact List | CONTACT_LIST | List containing contacts or roles for a project. NOTE: You can use the contactOptions property to specify a pre-defined list of values for the column, which can also become lanes in card view. |
Contact List | MULTI_CONTACT_LIST | List where single cells can contain more than one contact. Only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying. To see email addresses behind the display names, combine an include=objectValue query parameter with a level query parameter. |
Date | DATE | |
Date/Time | ABSTRACT_DATETIME | Represents a project sheet's start and end dates. Only for dependency-enabled project sheets The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) Additionally, the API does not support updating data in the "End Date" column under any circumstance, and does not support updating data in the "Start Date" column if "Predecessor" is set for that row. |
Date/Time | DATETIME | Used only by the following system-generated columns:
|
Dropdown List | PICKLIST | Custom, RYG, Harvey ball, priority types, etc. |
Dropdown List | MULTI_PICKLIST | List where single cells can contain more than one dropdown item. Only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying. To see multi-picklist values behind the display names, combine an include=objectValue query parameter with a level query parameter. |
Duration | DURATION | Only for dependency-enabled project sheets The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) |
Predecessor | PREDECESSOR | Defines what must happen first in a project flow. For more information, see the Predecessor object. Only for dependency-enabled project sheets |
Text/Number | TEXT_NUMBER |
Symbol Columns
In addition to the basic column types above, the Smartsheet app also supports columns that display symbols. These are specialized columns of type CHECKBOX or PICKLIST, whose symbol attribute is set to one of the values below:
Symbols for CHECKBOX columns:
Value | Example |
---|---|
FLAG | ![]() |
STAR | ![]() |
Symbols for PICKLIST columns:
Value | Example |
---|---|
ARROWS_3_WAY | ![]() |
ARROWS_4_WAY | ![]() |
ARROWS_5_WAY | ![]() |
DECISION_SHAPES | ![]() |
DECISION_SYMBOLS | ![]() |
DIRECTIONS_3_WAY | ![]() |
DIRECTIONS_4_WAY | ![]() |
EFFORT | ![]() |
HARVEY_BALLS | ![]() |
HEARTS | ![]() |
MONEY | ![]() |
PAIN | ![]() |
PRIORITY | ![]() |
PRIORITY_HML | ![]() |
PROGRESS | ![]() |
RYG | ![]() |
RYGB | ![]() |
RYGG | ![]() |
SIGNAL | ![]() |
SKI | ![]() |
STAR_RATING | ![]() |
VCR | ![]() |
WEATHER | ![]() |
System Columns
In addition to the standard column types and symbols, Smartsheet has a number of system columns, which represent data that is filled in by Smartsheet and whose values cannot be changed by the user. These columns are represented with standard column types, with the Column.systemColumnType attribute set to one of the following:
Column.systemColumnType Value | Column Type | Notes |
---|---|---|
AUTO_NUMBER | TEXT_NUMBER | Columns of this system column type include an AutoNumberFormat object that describes the mask used to generate the value. |
CREATED_BY | CONTACT_LIST | |
CREATED_DATE | DATETIME | |
MODIFIED_BY | CONTACT_LIST | |
MODIFIED_DATE | DATETIME |
Comments
A discussion is a container for a number of individual comments in a threaded conversation. For more details, see the Discussion section.​
This section describes operations on an individual comment within a discussion thread.
- To retrieve all discussions and comments for an entire sheet, use List Discussions with the ​query parameter​ include​=comments​.
- To retrieve all discussions and comments associated with a row, use List Row Discussions ​with the​ query parameter​ include​=comments​.
Objects
Comment Object
Example: Comment object
{
"text": "This is a comment",
"createdBy" : {"name": "John Doe", "email" : "john.doe@smartsheet.com"},
"createdAt" : "2013-06-24T21:07:45Z",
"modifiedAt" : "2013-06-24T21:07:45Z",
"discussionId" : 48569348493469348,
"id": 48569348493401200
}
id | number | Comment Id |
discussionId | number (optional) | Discussion Id |
attachments | Attachment[] | Array of Attachment objects |
createdAt | timestamp | Time of creation |
createdBy | User | User object containing name and email of the comment's author |
modifiedAt | timestamp | Time of last modification |
text | string | Comment body |
Add Comment
Example request: add comment (without attachment)
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"text":"This is a new comment."}'
// Specify comment
var comment = { "text": "This is a new comment." };
// Set options
var options = {
sheetId: 2252168947361668,
discussionId: 3962273862576004,
body: comment
};
// Add comment to discussion
smartsheet.sheets.addDiscussionComment(options)
.then(function(newComment) {
console.log(newComment);
})
.catch(function(error) {
console.log(error);
});
// Create comment
Comment commentSpecification = new Comment
{
Text = "This is a new comment."
};
// Add comment to discussion
Comment newComment = smartsheet.SheetResources.DiscussionResources.CommentResources.AddComment(
2252168947361668, // sheetId
3962273862576004, // discussionId
commentSpecification
);
// Create comment
Comment commentSpecification = new Comment()
.setText("This is a new comment.");
// Add comment to discussion
Comment newComment = smartsheet.sheetResources().discussionResources().commentResources().addComment(
2252168947361668L, // long sheetId
3962273862576004L, // long discussionId
commentSpecification
);
response = smartsheet_client.Discussions.add_comment_to_discussion(
2252168947361668, # sheet_id
3962273862576004, # discussion_id
smartsheet.models.Comment({
'text': 'This is a new comment.'
})
)
body = {
text: 'This is a new comment.'
}
response = smartsheet.sheets.comments.add(
sheet_id: 2252168947361668,
discussion_id: 3962273862576004,
body: body
)
new_comment = response[:result]
Example request: add comment (with attachment)
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F 'comment={ "text":"This is a new comment." };type=application/json' \
-F "file=@insurance_benefits.pdf;type=application/octet-stream"
// Multipart operations are not supported by the Node SDK. Instead, see instructions to Add Comment, and then Attach File to Comment.
// Create comment
Comment commentSpecification = new Comment
{
Text = "This is a new comment."
};
// Add comment (with attachment) to discussion
Comment newComment = smartsheet.SheetResources.DiscussionResources.CommentResources.AddCommentWithAttachment(
2252168947361668, // sheetId
3962273862576004, // discussionId
commentSpecification,
filePath,
"application/octet-stream"
);
// Create comment
Comment commentSpecification = new Comment()
.setText("This is a new comment.");
// Add comment (with attachment) to discussion
File file = new File(filePath);
smartsheet.sheetResources().discussionResources().commentResources().addCommentWithAttachment(
2252168947361668L, // long sheetId
3962273862576004L, // long discussionId
commentSpecification,
file,
"application/octet-stream"
);
# Create comment
comment = smartsheet.models.Comment({
'text': 'This is a new comment.'
})
# Add comment (with attachment) to discussion
response = smartsheet_client.Discussions.add_comment_to_discussion_with_attachment(
2252168947361668, # sheet_id
3962273862576004, # discussion_id
comment,
('image.png', open('/path/to/image.png', 'rb'), 'image/png')
)
# Multipart operations are not supported by the Ruby SDK. Instead, see instructions to Add Comment, and then Attach File to Comment.
Example response
{
"message": "SUCCESS",
"result": {
"createdAt": "2013-02-28T22:58:30-08:00",
"createdBy": {
"email": "john.doe@smartsheet.com",
"name": "John Doe"
},
"id": 6834973207488388,
"modifiedAt": "2013-02-28T22:58:30-08:00",
"text": "This is a new comment."
},
"resultCode": 0
}
POST /sheets/{sheetId}/discussions/{discussionId}/comments
Adds a comment to a discussion.
Creating a Comment without an Attachment
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Comment object with the following attribute:
|
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:
|
Returns | Result object containing a Comment object for the newly created comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment. |
Access Scope | WRITE_SHEETS |
Edit Comment
Example request: edit comment
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X PUT \
-d '{"text":"This is the updated comment text."}'
// Specify text
var body = {
text: "This is the updated comment text."
};
// Set options
var options = {
sheetId: 3285357287499652,
commentId: 7144101943502724,
body: body
};
// Edit comment
smartsheet.sheets.editComment(options)
.then(function(updatedComment) {
console.log(updatedComment);
})
.catch(function(error) {
console.log(error);
});
// Specify edited comment properties
Comment commentSpecification = new Comment
{
Id = 7144101943502724,
Text = "This is the updated comment text"
}
// Edit comment
Comment updatedComment = smartsheet.SheetResources.DiscussionResources.CommentResources.UpdateComment(
3285357287499652, // sheetId
commentSpecification
);
[todo]
comment = smartsheet_client.Discussions.update_comment(
3285357287499652, # sheet_id
7144101943502724, # comment_id
smartsheet.models.Comment({
'text': 'This is the updated comment text'}))
body = {
text: 'This is the updated comment text'
}
response = smartsheet.sheets.comments.update(
sheet_id: 3285357287499652,
comment_id: 7144101943502724,
body: body
)
updated_comment = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 7144101943502724,
"discussionId": 4503677744506756,
"text": "This is the updated comment text.",
"createdBy": {
"name": "John Doe",
"email": "john.doe@smartsheet.com"
},
"createdAt": "2013-01-10T13:43:26Z",
"modifiedAt": "2013-01-12T19:00:26Z"
},
"version": 18
}
PUT /sheets/{sheetId}/comments/{commentId}
Updates the text of a comment. NOTE: Only the user that created the comment is permitted to update it.
Updating a Comment
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Comment object with the following attribute:
|
Returns | Result object containing Comment object that was updated |
Access Scope | WRITE_SHEETS |
Delete Comment
Example request: delete comment
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"\
-X 'DELETE'
// Set options
var options = {
sheetId: 2252168947361668,
commentId: 4952999001909124
};
// Delete comment
smartsheet.sheets.deleteComment(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.SheetResources.CommentResources.DeleteComment(
2252168947361668, // sheetId
4952999001909124 // commentId
);
smartsheet.sheetResources().commentResources().deleteComment(
2252168947361668L, // long sheetId
4952999001909124L // long commentId
);
smartsheet_client.Discussions.delete_discussion_comment(
2252168947361668, # sheet_id
4952999001909124) # comment_id
smartsheet.sheets.comments.delete(
sheet_id: 2252168947361668,
comment_id: 4952999001909124
)
Example response
{
"message" : "SUCCESS",
"resultCode": 0,
"version": 12
}
DELETE /sheets/{sheetId}/comments/{commentId}
Deletes the comment specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | WRITE_SHEETS |
Get Comment
Example request: get comment
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 2252168947361668,
commentId: 48569348493401200
};
// Get comment
smartsheet.sheets.getComment(options)
.then(function(comment) {
console.log(comment);
})
.catch(function(error) {
console.log(error);
});
Comment comment = smartsheet.SheetResources.CommentResources.GetComment(
2252168947361668, // sheetId
48569348493401200 // commentId
);
Comment comment = smartsheet.sheetResources().commentResources().getComment(
2252168947361668L, // long sheetId
4856934849340120L // long commentId
);
comment = smartsheet_client.Discussions.get_discussion_comment(
2252168947361668, # sheet_id
4856934849340120) # comment_id
comment = smartsheet.sheets.comments.get(
sheet_id: 2252168947361668,
comment_id: 4856934849340120
)
Example response
{
"text": "This is a comment",
"createdBy" : {"name": "John Doe", "email" : "john.doe@smartsheet.com"},
"createdAt" : "2013-06-24T21:07:45Z",
"modifiedAt" : "2013-06-24T21:07:45Z",
"discussionId" : 4503677744506756,
"id": 48569348493401200
}
GET /sheets/{sheetId}/comments/{commentId}
Gets the comment specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Comment object |
Access Scope | READ_SHEETS |
Related Items
A comment can contain one or more attachments.
Comment Attachments
For details about working with a comment's attachments, see Attachments.
Contacts
A contact is a user's personal contact in Smartsheet (as described in the Help Center article, Managing Contacts).
Objects
Contact Object
Example: Contact object
{
"id": "AAAAATYU54QAD7_fNhTnhA",
"name": "David Davidson",
"email": "dd@example.com"
}
id | string | Contact Id |
string | Contact's email address | |
name | string | Contact's full name |
Get Contact
Example request: get contact
curl https://api.smartsheet.com/2.0/contacts/{contactId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {id: "AAAAATYU54QAD7_fNhTnhA"};
// Get contact
smartsheet.contacts.getContact(options)
.then(function(contact) {
console.log(contact);
})
.catch(function(error) {
console.log(error);
});
Contact contact = smartsheet.ContactResources.GetContact(
"AAAAATYU54QAD7_fNhTnhA" // string contactId
);
Contact contact = smartsheet.contactResources().getContact(
"AAAAATYU54QAD7_fNhTnhA" // string contactId
);
contact = smartsheet_client.Contacts.get_contact(
'AAAAATYU54QAD7_fNhTnhA') # contact_id
contact = smartsheet.contacts.get(
contact_id: 'AAAAATYU54QAD7_fNhTnhA'
)
Example response
{
"id": "AAAAATYU54QAD7_fNhTnhA",
"name": "David Davidson",
"email": "dd@example.com"
}
GET /contacts/{contactId}
Gets the specified contact.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | include (optional) -- comma-separated list of elements to copy:
|
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:
|
Create Cross-sheet References
Example request: create cross-sheet references
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/crosssheetreferences \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "Sample Time Log Sheet Range 1",
"sourceSheetId": 154378742065028,
"startRowId": 4089096300717956,
"endRowId": 2681721417164676,
"startColumnId": 824812248557444,
"endColumnId": 824812248557444
}'
var body = {
name: "my cross sheet reference",
sourceSheetId: 154378742065028,
startRowId: 4089096300717956,
endRowId: 2681721417164676,
"startColumnId": 824812248557444,
"endColumnId": 824812248557444
};
smartsheet.sheets.createCrossSheetReference({sheetId: 456745674567, body: body})
.then((result) => {
console.log("success");
console.log(JSON.stringify(result));
})
.catch((error) => {
console.log("error");
console.log(JSON.stringify(error));
});
CrossSheetReference xref = new CrossSheetReference();
xref.Name = "Sample Time Log Sheet Range 1";
xref.SourceSheetId = 154378742065028;
xref.StartRowId = 4089096300717956;
xref.EndRowId = 2681721417164676;
xref.StartColumnId = 824812248557444;
xref.EndColumnId = 824812248557444;
CrossSheetReference newXRef = smartsheet.SheetResources.CrossSheetReferenceResources.CreateCrossSheetReference(
1755440242550660, //sheetId
xref
);
CrossSheetReference xref = new CrossSheetReference();
xref.setName("Sample Time Log Sheet Range 1");
xref.setSourceSheetId(154378742065028L);
xref.setStartRowId(4089096300717956L);
xref.setEndRowId(2681721417164676L);
xref.setStartColumnId(824812248557444L);
xref.setEndColumnId(824812248557444L);
CrossSheetReference newXRef = smartsheet.sheetResources().crossSheetReferenceResources().createCrossSheetReference(
1755440242550660, //sheetId
xref
);
xref = smartsheet.models.CrossSheetReference({
'name': 'Sample Time Log Sheet Range 1',
'source_sheet_id': 154378742065028,
'start_row_id': 4089096300717956,
'end_row_id': 2681721417164676,
'start_column_id': 824812248557444,
'end_column_id': 824812248557444
})
result = smartsheet_client.Sheets.create_cross_sheet_reference(
1755440242550660, xref)
smartsheet.sheets.cross_sheet_references.create(
sheet_id: 8157685695702916,
body: {
name: "Sample Time Log Sheet Range 1",
source_sheet_id: 154378742065028,
start_row_id: 4089096300717956,
end_row_id: 2681721417164676,
start_column_id: 824812248557444,
end_column_id: 824812248557444
}
)
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"name": "Sample Time Log Sheet Range 1",
"sourceSheetId": 154378742065028,
"startRowId": 4089096300717956,
"endRowId": 2681721417164676,
"startColumnId": 824812248557444,
"endColumnId": 824812248557444
}
}
POST /sheets/{sheetId}/crosssheetreferences
Adds a cross-sheet reference between two sheets and defines the data range for formulas. Each distinct data range requires a new cross-sheet reference.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | CrossSheetReference object with the following attributes:
|
Returns | Result object containing a CrossSheetReference object, corresponding to what was specified in the request. |
Access Scope | CREATE_SHEETS |
Get Cross-sheet Reference
Example request: get cross-sheet references
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/crosssheetreferences/{crossSheetReferenceId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
smartsheet.sheets.getCrossSheetReference({sheetId: 9283173393803140, crossSheetReferenceId: 8157685695702916})
.then((result) => {
console.log("success");
console.log(JSON.stringify(result));
})
.catch((error) => {
console.log("error");
console.log(JSON.stringify(error));
});
CrossSheetReference xref = smartsheet.SheetResources.CrossSheetReferenceResources.GetCrossSheetReference(
9283173393803140, // sheetId
8157685695702916 // crossSheetReferenceId
);
CrossSheetReference xref = smartsheet.sheetResources().crossSheetReferenceResources().getCrossSheetReference(
9283173393803140L, // sheetId
8157685695702916L // crossSheetReferenceId
);
result = smartsheet_client.Sheets.get_cross_sheet_reference(
9283173393803140, # sheet_id
8157685695702916 # cross_sheet_reference_id
)
smartsheet.sheets.cross_sheet_references.get(
sheet_id: 9283173393803140,
cross_sheet_reference_id: 8157685695702916
)
Example response
{
"id": 8157685695702916,
"status": "OK",
"name": "Sample Time Log Sheet Range 1",
"sourceSheetId": 154378742065028,
"startRowId": 4089096300717956,
"endRowId": 2681721417164676,
"startColumnId": 824812248557444,
"endColumnId": 824812248557444
}
GET /sheets/{sheetId}/crosssheetreferences/{crossSheetReferenceId}
Gets the cross-sheet reference specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | CrossSheetReference object |
Access Scope | READ_SHEETS |
List Cross-sheet References
Example request: list cross-sheet references
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/crosssheetreferences \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
smartsheet.sheets.listCrossSheetReferences({sheetId: 9283173393803140})
.then((result) => {
console.log("success");
console.log(JSON.stringify(result));
})
.catch((error) => {
console.log("error");
console.log(JSON.stringify(error));
});
//Sample 1: List all
smartsheet.SheetResources.CrossSheetReferenceResources.ListCrossSheetReferences(
9283173393803140, // sheetId
null // PaginationParameters
);
//Sample 2: Paginate the list
PaginationParameters paginationParameters = new PaginationParameters(
false, // includeAll
100, // pageSize
1 // page
);
smartsheet.SheetResources.CrossSheetReferenceResources.ListCrossSheetReferences(
9283173393803140, // sheetId
paginationParameters
);
//Sample 1: List all
smartsheet.sheetResources().crossSheetReferenceResources().listCrossSheetReferences(
9283173393803140L, // sheetId
null // PaginationParameters
);
//Sample 2: Paginate the list
PaginationParameters paginationParameters = new PaginationParameters(
false, // includeAll
100, // pageSize
1 // page
);
smartsheet.sheetResources().crossSheetReferenceResources().listCrossSheetReferences(
9283173393803140L, // sheetId
paginationParameters
);
result = smartsheet_client.Sheets.list_cross_sheet_references(
9283173393803140)
smartsheet.sheets.cross_sheet_references.list(
sheet_id: 9283173393803140
)
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 6,
"data": [
{
"id": 2545778347534212,
"status": "OK",
"name": "Data Sheet Range 1",
"sourceSheetId": 1244271622809476,
"startColumnId": 6905486478993284,
"endColumnId": 545911223936900
},
{
"id": 8157685695702916,
"status": "OK",
"name": "Sample Time Log Sheet Range 1",
"sourceSheetId": 154378742065028,
"startRowId": 4089096300717956,
"endRowId": 2681721417164676,
"startColumnId": 824812248557444,
"endColumnId": 824812248557444
}
]
}
GET /sheets/{sheetId}/crosssheetreferences
Lists all cross-sheet references for the sheet.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | IndexResult object containing an array of CrossSheetReference objects |
Access Scope | READ_SHEETS |
Dashboards
Smartsheet Dashboards are a collection of widgets that can contain data from a variety of different data sources (for example, sheets, reports, or custom data). Dashboards were once called Sights(TM) and this name is still present in object names, endpoint paths, and other places.
Objects
Dashboard Object
Example: Dashboard object
{
"id": 2591554075418573,
"name": "Test",
"accessLevel": "OWNER",
"columnCount": 6,
"widgets": []
}
id | number | Dashboard Id |
accessLevel | string | User's permissions on the dashboard. Valid values:
|
backgroundColor | hex | The hex color, for instance #E6F5FE |
columnCount | number | Number of columns that the dashboard contains |
createdAt | timestamp | Time of creation |
favorite | Boolean | Indicates whether the user has marked the dashboard as a favorite |
modifiedAt | timestamp | Time of last modification |
name | string | Dashboard name |
permalink | string | URL that represents a direct link to the dashboard in Smartsheet |
source | source | A Source object indicating the dashboard from which this dashboard was created, if any |
widgets | widget[] | Array of Widget objects |
workspace | Workspace | A Workspace object, limited to only 2 attributes:
|
SightPublish Object
readOnlyFullAccessibleBy | string | Indicates who can access the 'Read-Only Full' view of the published dashboard:
|
readOnlyFullEnabled | Boolean | If true, a rich version of the dashboard is published with the ability to use shortcuts and widget interactions. |
readOnlyFullUrl | string | URL for 'Read-Only Full' view of the published dashboard. Only returned in a response if readOnlyFullEnabled = true. |
Widget Object
Example: Widget object
{
"id": 3056651398234562,
"type": "RICHTEXT",
"contents": {
"htmlContent": "<p>This is a test</p>"
},
"xPosition": 2,
"yPosition": 0,
"width": 2,
"height": 4,
"showTitleIcon": false,
"titleFormat": ",,1,,,,,,,3,,,,,,",
"version": 1
}
id | number | Widget Id |
type | string | Type of widget. See table below to see how UI widget names map to type. |
contents | WidgetContent object | Data that specifies the contents of the widget. NOTE: The type of WidgetContent object (and attributes within) depends on the value of widget.type. |
height | number | Number of rows that the widget occupies on the dashboard |
showTitle | Boolean | True indicates that the client should display the widget title. NOTE: This is independent of the title string which may be null or empty. |
showTitleIcon | Boolean | True indicates that the client should display the sheet icon in the widget title |
title | string | Title of the widget |
titleFormat | string | FormatDescriptor |
version | int | Widget version number |
viewMode | int | 1 indicates content is centered. 2 indicates content is left aligned. Must use a query parameter of level=2 to see this information. |
width | number | Number of columns that the widget occupies on the dashboard |
xPosition | number | X-coordinate of widget's position on the dashboard |
yPosition | number | Y-coordinate of widget's position on the dashboard |
UI widget name | type string | Object |
---|---|---|
Chart | CHART | ChartWidgetContent |
Image | IMAGE | ImageWidgetContent |
Metric | SHEETSUMMARY or METRIC | CellLinkWidgetContent |
Report | GRIDGANTT | ReportWidgetContent |
Rich Text | RICHTEXT | RichTextWidgetContent |
Shortcut | SHORTCUTICON, SHORTCUTLIST, or SHORTCUT | ShortcutWidgetContent |
Title | TITLE | TitleWidgetContent |
Web Content | WEBCONTENT | WebContentWidgetContent |
CellLinkWidgetContent Object
sheetId | number | The Id of the sheet from which the cell data originates |
cellData | CellDataItem[] | Array of CellDataItem objects |
columns | Column[] | Array of Column objects |
hyperlink | WidgetHyperlink | The widget has when clicked attribute set to that hyperlink (if present and non-null) |
CellDataItem Object
columnId | number | Column Id for each item |
rowId | number | Row Id for each item |
sheetId | number | Sheet Id for each item |
objectValue | A string, number, or a Boolean value | The type of data returned depends on the cell type and the data in the cell |
cell | Cell | Cell object |
dataSource | string | CELL |
label | string | Label for the data point. This is either the column name or a user-provided string |
labelFormat | string | formatDescriptor |
order | integer | The display order for the CellDataItem |
profileField | SummaryField | SummaryField object |
valueFormat | string | formatDescriptor |
ChartWidgetContent Object
reportId | number | Report Id denoting container source, if applicable |
sheetId | number | Sheet Id denoting container source, if applicable |
axes | Axes[] | Array of Axes objects |
hyperlink | WidgetHyperlink | The widget has when clicked attribute set to that hyperlink (if present and non-null) |
includedColumnIds | includedColumnIds[]] | Array of columnIds if the range was selected through the UI |
legend | string | The location in the widget where Smartsheet renders the legend, for example, RIGHT |
selectionRanges | SelectionRange[] | If the source is a sheet |
series | Series[] | Array of Series objects |
ImageWidgetContent Object
privateId | string | The image private Id |
fileName | string | Name of the image file |
format | string | formatDescriptor |
height | integer | Original height of the image in pixels |
hyperlink | WidgetHyperlink | The widget has when clicked attribute set to that hyperlink (if present and non-null). Hyperlinks will have interactionType. |
width | integer | Original width of the image in pixels |
ReportWidgetContent Object
reportId | number | Report Id denoting container source |
htmlContent | string | HTML snippet to render report |
hyperlink | WidgetHyperlink | The widget has when clicked attribute set to that hyperlink (if present and non-null). Hyperlinks will have interactionType. |
RichTextWidgetContent Object
html | string | The widget content as HTML The Rich Text widget supports the following subset of HTML tags and CSS Styles: HTML
|
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:
|
folderId | number | If interactionType = SMARTSHEET_ITEM this is the folder to open |
reportId | number | If interactionType = SMARTSHEET_ITEM this is the report to open |
sheetId | number | If interactionType = SMARTSHEET_ITEM this is the sheet to open |
sightId | number | If interactionType = SMARTSHEET_ITEM this is the dashboard to open |
url | string | If interactionType = WEB this is the URL to launch |
workspaceId | number | If interactionType = SMARTSHEET_ITEM this is the workspace to open |
Copy Dashboard
Example request: copy dashboard
curl https://api.smartsheet.com/2.0/sights/{sightId}/copy \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"
-d '{
"destinationType": "workspace",
"destinationId": 7960873114331012,
"newName": "newDashboardName"
}' \
-X POST
// Specify new dashboard properties
var body = {
destinationType: "home",
newName: "newDashboardName"
};
// Set options
var options = {
sightId: 6327127650920324,
body: body
};
// Copy Dashboard
smartsheet.sights.copySight(options)
.then(function(copiedSight) {
console.log(copiedSight);
})
.catch(function(error) {
console.log(error);
});
// Specify destination
ContainerDestination destination = new ContainerDestination
{
DestinationId = 3791509922310020, // long destinationFolderId
DestinationType = DestinationType.FOLDER,
NewName = "newDashboardName"
};
// Copy Dashboard
Sight sight = smartsheet.SightResources.CopySight(
6327127650920324, // long sightId
destination
);
// Specify destination
ContainerDestination destination = new ContainerDestination()
.setDestinationType(DestinationType.FOLDER)
.setDestinationId(3791509922310020L)
.setNewName("newDashboardName");
// Copy Dashboard
Sight sight = smartsheet.sightResources().copySight(
6327127650920324L, // long sightId
destination
);
new_sight = smartsheet_client.Sights.copy_sight(
6327127650920324, # sight_id
smartsheet.models.ContainerDestination({
'destination_type': 'folder', # folder, workspace, or home
'destination_id': 3791509922310020, # folder_id
'new_name': 'newDashboardName'
})
)
# Specify destination
body = {
destination_type: 'folder',
destination_id: 3791509922310020,
new_name: 'newDashboardName'
}
# Copy Dashboard
new_sight = smartsheet.sights.copy(
sight_id: 6327127650920324,
body: body
)
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 4583173393803140,
"name": "newDashboardName",
"accessLevel": "OWNER",
"permalink": "https://app.smartsheet.com/b/home?lx=lB0JaOh6AX1wGwqxsQIMaA"
}
}
POST /sights/{sightId}/copy
Creates a copy of the specified dashboard.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | ContainerDestination object |
Returns | Result object containing a Dashboard object for the newly created dashboard, limited to the following attributes:
|
Access Scope | CREATE_SIGHTS |
Delete Dashboard
Example request: delete dashboard
curl https://api.smartsheet.com/2.0/sights/{sightId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
// Set options
var options = {
sightId: 5363568917931908
};
// Delete Dashboard
smartsheet.sights.deleteSight(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.SightResources.DeleteSight(
5077532685952900 // sightId
);
smartsheet.sightResources().deleteSight(
3100061023397764L // long sightId
);
smartsheet_client.Sights.delete_sight(3404239197235076) # sight_id
smartsheet.sights.delete(
sight_id: 6327127650920324
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /sights/{sightId}
Deletes the dashboard specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | DELETE_SIGHTS |
Get Dashboard
Example request: get dashboard
curl https://api.smartsheet.com/2.0/sights/{sightId}?level=4 \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sightId: 6327127650920324
};
// Get dashboard
smartsheet.sights.getSight(options)
.then(function(sight) {
console.log(sight);
})
.catch(function(error) {
console.log(error);
});
Sight sight = smartsheet.SightResources.GetSight(
6327127650920324 // long sightId
);
Sight sight = smartsheet.sightResources().getSight(
6327127650920324L // long sightId
);
sight = smartsheet_client.Sights.get_sight(
6327127650920324) # sightId
sight = smartsheet.sights.get(
sight_id: 6327127650920324
)
Example response
{
"id": 2591554075418573,
"name": "Test",
"accessLevel": "OWNER",
"columnCount": 6,
"widgets": [
{
"id": 3056651398234562,
"type": "RICHTEXT",
"contents": {
"htmlContent": "<p>This is a test</p>"
},
"xPosition": 2,
"yPosition": 0,
"width": 2,
"height": 4,
"showTitleIcon": false,
"titleFormat": ",,1,,,,,,,3,,,,,,",
"version": 1
},
{
"id": 9996257304487812,
"type": "METRIC",
"contents": {
"type": "METRIC",
"cellData": [
{
"label": "test summary here",
"labelFormat": ",2,,,,,,,1,,,,,,,1,",
"valueFormat": ",2,1,,,,1,,1,3,,,,,,1,",
"order": 0,
"profileField": {
"id": 9992738687018884,
"index": 0,
"title": "test summary here",
"type": "TEXT_NUMBER",
"locked": false,
"lockedForUser": false,
"objectValue": "summary content",
"displayValue": "summary content",
"createdAt": "2019-10-31T22:01:19Z",
"modifiedAt": "2019-10-31T22:01:19Z"
},
"dataSource": "SUMMARY_FIELD",
"objectValue": "summary content"
}
],
"sheetId": 663216503187332,
"viewMode": 2
},
"xPosition": 0,
"yPosition": 0,
"width": 15,
"height": 7,
"title": "test sheet for charts",
"showTitleIcon": true,
"showTitle": true,
"titleFormat": ",,1,,,,,,,3,,,,,,1,",
"version": 1
}
]
}
GET /sights/{sightId}
Gets the specified dashboard.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | include (optional) -- a comma-separated list of optional elements to include in the response:
|
level (optional): specifies whether new functionality, such as multi-contact data is returned in a backwards-compatible, text format (level=0, default), multi-contact data (level=2), multi-picklist data (level=3), or Metric widget with sheet summary (level=4). | |
objectValue (optional) -- when used in combination with a level query parameter, includes the email addresses for multi-contact data. | |
Returns | Dashboard object |
Access Scope | READ_SIGHTS |
List Dashboards
Example request: list dashboards
curl https://api.smartsheet.com/2.0/sights \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
smartsheet.sights.listSights()
.then(function(sights) {
console.log(sights.data);
})
.catch(function(error) {
console.log(error);
})
PaginatedResult<Sight> sights = smartsheet.SightResources.ListSights(
null, // PaginationParameters
null // Nullable<DateTime> modifiedSince
);
PagedResult<Sight> sights = smartsheet.sightResources().listSights(
null, // PaginationParameters
null // Date modifiedSince
);
response = smartsheet_client.Sights.list_sights(include_all=True)
sights = response.data
response = smartsheet.sights.list
sights = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [
{
"id": 2331373580117892,
"name": "Sales Dashboard",
"accessLevel": "OWNER",
"permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJesvSHCQ",
"createdAt": "2016-01-28T00:24:41Z",
"modifiedAt": "2016-01-28T20:32:33Z"
},
{
"id": 7397923160909700,
"name": "Dashboard #2",
"accessLevel": "OWNER",
"permalink": "https://app.smartsheet.com/b/home?lx=xUefSOIYmn07iJJrthEFTG",
"createdAt": "2016-01-28T01:17:51Z",
"modifiedAt": "2016-01-28T20:32:27Z"
}
]
}
GET /sights
Gets a list of all dashboards that the user has access to.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | modifiedSince (optional): when specified with a date and time value, response only includes the objects that are modified on or after the date and time specified. If you need to keep track of frequent changes, it may be more useful to use Get Sheet Version. |
This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. | |
Returns | IndexResult object containing an array of Dashboard objects limited to the following attributes:
|
Access Scope | READ_SIGHTS |
Move Dashboard
Example request: move dashboard
curl https://api.smartsheet.com/2.0/sights/{sightId}/move \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"
-d '{
"destinationType": "folder",
"destinationId": workspace_or_folder_id
}' \
-X POST
// Set destination
var body = {
destinationType: "folder",
destinationId: 8460057768683396
};
// Set options
var options = {
sightId: 5077532685952900,
body: body
};
// Move Dashboard
smartsheet.sights.moveSight(options)
.then(function(movedSight) {
console.log(movedSight);
})
.catch(function(error) {
console.log(error);
});
// Specify destination
ContainerDestination destination = new ContainerDestination
{
DestinationId = 8460057768683396, // long destinationFolderId
DestinationType = DestinationType.FOLDER
};
// Move Dashboard
Sight sight = smartsheet.SightResources.MoveSight(
5077532685952900, // long sightId
destination
);
// Specify destination
ContainerDestination destination = new ContainerDestination()
.setDestinationType(DestinationType.FOLDER)
.setDestinationId(7960873114331012L);
// Move Dashboard
Sight sight = smartsheet.sightResources().moveSight(
4583173393803140L, // long sightId
destination
);
response = smartsheet_client.Sights.move_sight(
5363568917931908, # sight_id
smartsheet.models.ContainerDestination({
'destination_type': 'folder', # folder, workspace, or home
'destination_id': 8460057768683396 # destination folder_id
})
)
# Specify destination
body = {
destination_type: 'folder',
destination_id: 8460057768683396
}
# Move Dashboard
response = smartsheet.sights.move(
sight_id: 5363568917931908,
body: body
)
moved_sight = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 4583173393803140,
"name": "moved_dashboard_name",
"accessLevel": "OWNER",
"permalink": "https://app.smartsheet.com/b/home?lx=lB0JaOh6AX1wGwqxsQIMaA"
}
}
POST /sights/{sightId}/move
Moves the specified dashboard to a new location.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | ContainerDestination object, limited to the following required attributes:
|
Returns | Result object containing a Dashboard object for the moved dashboard, limited to the following attributes:
|
Access Scope | CREATE_SIGHTS |
Publish Dashboard
Get Dashboard Publish Status
Example request: get dashboard publish status
curl https://api.smartsheet.com/2.0/sights/{sightId}/publish \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sightId: 5363568917931908
};
// Get dashboard publish status
smartsheet.sights.getSightPublishStatus(options)
.then(function(status) {
console.log(status);
})
.catch(function(error) {
console.log(error);
});
SightPublish publish = smartsheet.SightResources.GetPublishStatus(
5363568917931908 // sightId
);
SightPublish publish = smartsheet.sightResources().getPublishStatus(
5363568917931908L // long sightId
);
status = smartsheet_client.Sights.get_publish_status(
5363568917931908) # sight_id
status = smartsheet.sights.get_publish_status(
sight_id: 5363568917931908
)
Example response
{
"readOnlyFullEnabled": true,
"readOnlyFullAccessibleBy": "ALL",
"readOnlyFullUrl": "https://publish.smartsheet.com/6d35fa6c99334d4892f9591cf6065"
}
GET /sights/{sightId}/publish
Gets the dashboard 'publish' settings.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | SightPublish object |
Access Scope | READ_SIGHTS |
Set Dashboard Publish Status
Example request: set dashboard publish status
curl https://api.smartsheet.com/2.0/sights/{sightId}/publish \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
-H "Content-Type: application/json"
-X PUT
-d '{
"readOnlyFullEnabled": true,
"readOnlyFullAccessibleBy": "ALL"
}' \
// Specify property to change
var body = {
readOnlyFullEnabled: false
};
// Set options
var options = {
sightId: 5363568917931908,
body: body
};
// Set dashboard publish status
smartsheet.sights.setSightPublishStatus(options)
.then(function(newStatus) {
console.log(newStatus);
})
.catch(function(error) {
console.log(error);
});
SightPublish publish = new SightPublish();
publish.ReadOnlyFullEnabled = true;
smartsheet.SightResources.SetPublishStatus(
5363568917931908, // sightId
publish
);
SightPublish publish = new SightPublish();
publish.setReadOnlyFullEnabled(true);
smartsheet.sightResources().setPublishStatus(
5363568917931908L, // long sightId
publish
);
response = smartsheet_client.Sights.set_publish_status(
5363568917931908, # sight_id
smartsheet.models.SightPublish({
'read_only_full_enabled': True
})
)
# Set options
body = {
read_only_full_enabled: true,
read_only_full_accessible_by: 'ALL'
}
# Set dashboard publish status
response = smartsheet.sights.set_publish_status(
sight_id: 5363568917931908,
body: body
)
status = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"readOnlyFullEnabled": true,
"readOnlyFullAccessibleBy": "ORG",
"readOnlyFullUrl": "http://publish.smartsheet.com/9862638d9c444014b5d7a114d436e99d"
}
}
PUT /sights/{sightId}/publish
Publishes or unpublishes a dashboard.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | SightPublish object limited to the following attributes:
|
Returns | Result object containing a SightPublish object |
Access Scope | ADMIN_SIGHTS |
Share Dashboard
For details about dashboard sharing, see Dashboard Sharing.
Update Dashboard
Example request: update dashboard
curl https://api.smartsheet.com/2.0/sights/{sightId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name": "New Dashboard Name"}'
// Set property to change
var body = {
name: "New Dashboard Name"
};
// Set options
var options = {
sightId: 5363568917931908,
body: body
};
// Update Dashboard
smartsheet.sights.updateSight(options)
.then(function(updatedSight) {
console.log(updatedSight);
})
.catch(function(error) {
console.log(error);
});
Sight sight = smartsheet.SightResources.UpdateSight(
new Sight {
Id = 5363568917931908, // sightId
Name = "New Dashboard Name"
}
);
Sight sight = new Sight();
sight.setId(5363568917931908L); // long sightId
sight.setName("New Dashboard Name");
Sight updatedSight = smartsheet.sightResources().updateSight(sight);
updated_sight = smartsheet_client.Sights.update_sight(
5363568917931908, # sight_id
smartsheet.models.Sight({
'name': 'New Dashboard Name'
})
)
# Specify property to change
body = {
name: 'New Dashboard Name'
}
# Update Dashboard
response = smartsheet.sights.update(
sight_id: 5363568917931908,
body: body
)
updated_sight = response[:result]
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 5363568917931908,
"name": "New Dashboard Name",
"accessLevel": "OWNER",
"permalink": "https://app.smartsheet.com/b/home?lx=rBU8QqUVPCJ3geRgl7L8yQ"
}
}
PUT /sights/{sightId}
Updates (renames) the specified dashboard.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Dashboard object limited to the following attribute:
|
Returns | Result object containing the updated Dashboard object |
Access Scope | ADMIN_SIGHTS |
Discussions
A discussion is a container for a collection of individual comments within a single thread. A discussion can exist on a row or a sheet.
In the UI, Smartsheet creates a discussion to contain each top-level comment and subsequent replies into a single thread.
Using the API, you can only add a comment to a discussion. If the discussion doesn't already exist, you must create it first.
Objects
Discussion Object
Example: Discussion object
{
"id": 1848321770841988,
"title": "Lincoln",
"comments": [],
"commentCount": 1,
"accessLevel": "OWNER",
"parentType": "ROW",
"parentId": 3344087179913092,
"readOnly": false,
"lastCommentedAt": "2017-06-09T17:04:08Z",
"lastCommentedUser": {
"name": "Test User",
"email": "tester@smartsheet.com"
},
"createdBy": {
"name": "Test User",
"email": "tester@smartsheet.com"
}
}
id | number | Discussion Id |
parentId | number | Id of the directly associated row or sheet: present only when the direct association is not clear (see List Discussions) |
parentType | string | SHEET or ROW: present only when the direct association is not clear (see List Discussions) |
accessLevel | string | User's permissions on the discussion |
commentAttachments | Attachment[] | Array of Attachment objects |
commentCount | number | The number of comments in the discussion |
comments | Comment[] | Array of Comment objects |
createdBy | User | User object containing name and email of the creator of the discussion |
lastCommentedAt | timestamp | Time of most recent comment |
lastCommentedUser | User | User object containing name and email of the author of the most recent comment |
readOnly | Boolean | Indicates whether the user can modify the discussion |
title | string | Read Only. Discussion title automatically created by duplicating the first 100 characters of the top-level comment |
Create Discussion on Row
Example request: create discussion on row (without attachment)
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"comment": {"text":"This text is the body of the first comment"}}'
// Specify discussion
var discussion = {
"comment": {
"text": "This text is the body of the first comment"
}
};
// Set options
var options = {
sheetId: 2252168947361668,
rowId: 4293147074291588,
body: discussion
};
// Add discussion to row
smartsheet.sheets.createRowDiscussion(options)
.then(function(newDiscussion) {
console.log(newDiscussion);
})
.catch(function(error) {
console.log(error);
});
// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
Comment = new Comment
{
Text = "This text is the body of the first comment"
},
Comments = null // workaround for SDK issue
};
// Add discussion to row
Discussion newDiscussion = smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussion(
9283173393803140, // sheetId
0123456789012345, // rowId
discussionSpecification
);
// Create comment
Comment commentSpecification = new Comment()
.setText("This text is the body of the first comment");
// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion()
.setComment(commentSpecification)
.setComments(null); // workaround for SDK issue
// Add discussion to row
Discussion newDiscussion = smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(
9283173393803140L, // sheetId
0123456789012345L, // rowId
discussionSpecification
);
response = smartsheet_client.Discussions.create_discussion_on_row(
9283173393803140, # sheet_id
0123456789012345, # row_id
smartsheet.models.Discussion({
'comment': smartsheet.models.Comment({
'text': 'This text is the body of the first comment'
})
})
)
# Set options
body = {
comment: {
text: 'This text is the body of the first comment'
}
}
# Create discussion on row
response = smartsheet.sheets.discussions.create_on_row(
sheet_id: 4583173393803140,
row_id: 4293147074291588,
body: body
)
new_discussion = response[:result]
Example request: create discussion on row (with attachment)
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F 'discussion={ "comment": { "text": "This text is the body of the first comment" } };type=application/json' \
-F "file=@insurance_benefits.pdf;type=application/octet-stream"
// Multipart operations are not supported by the Node SDK. Instead, see instructions to Create Discussion on Row, and then Attach File to Comment.
// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
Comment = new Comment
{
Text = "This text is the body of the first comment"
},
Comments = null // workaround for SDK issue
};
// Add discussion to row
Discussion newDiscussion = smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussionWithAttachment(
9283173393803140, // sheetId
0123456789012345, // rowId
discussionSpecification,
filePath,
"application/octet-stream"
);
// Create comment
Comment commentSpecification = new Comment()
.setText("This text is the body of the first comment");
// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion()
.setComment(commentSpecification)
.setComments(null); // workaround for SDK issue
// Set file path
File file = new File(filePath);
// Add discussion to row
Discussion newDiscussion = smartsheet.sheetResources().rowResources().discussionResources().createDiscussionWithAttachment(
9283173393803140L, // long sheetId
0123456789012345L, // long rowId
discussionSpecification,
file,
"application/octet-stream"
);
# Add discussion to row
response = smartsheet_client.Discussions.create_discussion_on_row_with_attachment(
9283173393803140, # sheet_id
0123456789012345, # row_id
smartsheet.models.Discussion({
'comment': smartsheet.models.Comment({
'text': 'This text is the body of the first comment'
})
}),
('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')
)
# Multipart operations are not supported by the Ruby SDK. Instead, see instructions to Create Discussion on Row, and then Attach File to Comment.
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"comments": [{
"createdAt": "2013-02-28T22:00:56-08:00",
"createdBy": {
"email": "jane.doe@smartsheet.com",
"name": "Jane Doe"
},
"id": 4583173393803140,
"modifiedAt": "2013-02-28T22:00:56-08:00",
"text": "This text is the body of the first comment"
}],
"id": 4583173393803140,
"title": "This text is the body of the first comment"
},
"version": 12
}
POST /sheets/{sheetId}/rows/{rowId}/discussions
Creates a new discussion on a row.
Creating a Discussion without an Attachment
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Discussion object with the following attribute:
|
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:
|
Returns | Result object containing a Discussion object for the newly created discussion, which contains a Comment object for the initial discussion comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment. |
Access Scope | WRITE_SHEETS |
Create Discussion on Sheet
Example request: create discussion on sheet (without attachment)
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{"comment": {"text":"This text is the body of the first comment"}}'
// Specify discussion
var discussion = {
"comment": {
"text": "This text is the body of the first comment"
}
};
// Set options
var options = {
sheetId: 2252168947361668,
body: discussion
};
// Add discussion to sheet
smartsheet.sheets.createDiscussion(options)
.then(function(newDiscussion) {
console.log(newDiscussion);
})
.catch(function(error) {
console.log(error);
});
// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
Comment = new Comment
{
Text = "This text is the body of the first comment"
},
Comments = null // workaround for SDK issue
};
// Add discussion to sheet
Discussion newDiscussion = smartsheet.SheetResources.DiscussionResources.CreateDiscussion(
9283173393803140, // sheetId
discussionSpecification
);
// Create comment
Comment commentSpecification = new Comment()
.setText("This text is the body of the first comment");
// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion()
.setComment(commentSpecification)
.setComments(null); // workaround for SDK issue
// Add discussion to sheet
Discussion newDiscussion = smartsheet.sheetResources().discussionResources().createDiscussion(
9283173393803140L, // long sheetId
discussionSpecification
);
response = smartsheet_client.Discussions.create_discussion_on_sheet(
9283173393803140, # sheet_id
smartsheet.models.Discussion({
'comment': smartsheet.models.Comment({
'text': 'This text is the body of the first comment'
})
})
)
# Set options
body = {
comment: {
text: 'This text is the body of the first comment'
}
}
# Create discussion on sheet
response = smartsheet.sheets.discussions.create_on_sheet(
sheet_id: 4583173393803140,
body: body
)
new_discussion = response[:result]
Example request: create discussion on sheet (with attachment)
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: multipart/form-data" \
-X POST \
-F 'discussion={ "comment": { "text": "This text is the body of the first comment" } };type=application/json' \
-F "file=@file_to_attach;type=application/octet-stream" \
// Multipart operations are not supported by the Node SDK. Instead, see instructions to Create Discussion on Sheet, and then Attach File to Comment.
// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion
{
Comment = new Comment
{
Text = "This text is the body of the first comment"
},
Comments = null // workaround for SDK issue
};
// Add discussion (including comment with attachment) to sheet
Discussion newDiscussion = smartsheet.SheetResources.DiscussionResources.CreateDiscussionWithAttachment(
9283173393803140, // sheetId
discussionSpecification,
filePath,
"application/octet-stream"
);
// Create comment
Comment commentSpecification = new Comment()
.setText("This text is the body of the first comment");
// Create discussion (including the comment)
Discussion discussionSpecification = new Discussion()
.setComment(commentSpecification)
.setComments(null); // workaround for SDK issue
File file = new File(filePath);
// Add discussion (including comment with attachment) to sheet
Discussion newDiscussion = smartsheet.sheetResources().discussionResources().createDiscussionWithAttachment(
9283173393803140L, // long sheetId
discussionSpecification,
file,
"application/octet-stream"
);
response = smartsheet_client.Discussions.create_discussion_on_sheet_with_attachment(
9283173393803140, # sheet_id
smartsheet.models.Discussion({
'comment': smartsheet.models.Comment({
'text': 'This text is the body of the first comment'
})
}),
('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')
)
# Multipart operations are not supported by the Ruby SDK. Instead, see instructions to Create Discussion on Sheet, and then Attach File to Comment.
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"comments": [{
"createdAt": "2013-02-28T22:00:56-08:00",
"createdBy": {
"email": "jane.doe@smartsheet.com",
"name": "Jane Doe"
},
"id": 4583173393803140,
"modifiedAt": "2013-02-28T22:00:56-08:00",
"text": "This text is the body of the first comment"
}],
"id": 4583173393803140,
"title": "This text is the body of the first comment"
},
"version": 12
}
POST /sheets/{sheetId}/discussions
Creates a new discussion on a sheet.
Creating a Discussion without an Attachment
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Discussion object with the following attribute:
|
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:
|
Returns | Result object containing a Discussion object for the newly created discussion, which contains a Comment object for the initial discussion comment, which in turn contains an Attachment object for the attachment that was uploaded to the comment. |
Access Scope | WRITE_SHEETS |
Delete Discussion
Example request: delete discussion
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"\
-X 'DELETE'
// Set options
var options = {
sheetId: 2252168947361668,
discussionId: 991393444325252
};
// Delete discussion
smartsheet.sheets.deleteDiscussion(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.SheetResources.DiscussionResources.DeleteDiscussion(
9283173393803140, // sheetId
0123456789012345 // discussionId
);
smartsheet.sheetResources().discussionResources().deleteDiscussion(
9283173393803140L, // long sheetId
0123456789012345L // long discussionId
);
smartsheet_client.Discussions.delete_discussion(
9283173393803140, # sheet_id
0123456789012345) # discussion_id
smartsheet.sheets.discussions.delete(
sheet_id: 4583173393803140,
discussion_id: 3962273862576004
)
Example response
{
"message" : "SUCCESS",
"resultCode": 0
}
DELETE /sheets/{sheetId}/discussions/{discussionId}
Deletes the discussion specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | WRITE_SHEETS |
List Discussions
Example request: list discussions
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions?include=comments,attachments' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 3138415114905476
};
// List discussions
smartsheet.sheets.getDiscussions(options)
.then(function(discussionList) {
console.log(discussionList);
})
.catch(function(error) {
console.log(error);
});
// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<Discussion> results = smartsheet.SheetResources.DiscussionResources.ListDiscussions(
9283173393803140, // sheetId
null, // IEnumerable<DiscussionInclusion> include
null // PaginationParameters
);
// Sample 2: Specify 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true'
PaginatedResult<Discussion> results = smartsheet.SheetResources.DiscussionResources.ListDiscussions(
9283173393803140, // sheetId
new DiscussionInclusion[] { DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS },
new PaginationParameters(
true, // includeAll
null, // int pageSize
null) // int page
);
// Sample 1: Omit 'include' parameter and pagination parameters
PagedResult<Discussion> results = smartsheet.sheetResources().discussionResources().listDiscussions(
9283173393803140L, // long sheetId
null, // PaginationParameters
null // EnumSet<DiscussionInclusion> includes
);
// Sample 2: Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters()
.setIncludeAll(true);
// List discussions (specify 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true')
PagedResult<Discussion> results = smartsheet.sheetResources().discussionResources().listDiscussions(
9283173393803140L, // long sheetId
parameters,
EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS)
);
# Sample 1: List all
response = smartsheet_client.Discussions.get_all_discussions(
9283173393803140, # sheet_id
include_all=True)
discussions = response.data
# Sample 2: Paginate the list
response = smartsheet_client.Discussions.get_all_discussions(
9283173393803140, # sheet_id
page_size=10,
page=1)
pages = response.total_pages
discussions = response.data
response = smartsheet.sheets.discussions.list(
sheet_id: 4583173393803140
)
discussions = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 1,
"data": [
{
"id": 3138415114905476,
"title": "Lincoln",
"comments": [
{
"id": 7320407591151492,
"text": "16th President",
"createdBy": {
"name": "Test User",
"email": "tester@smartsheet.com"
},
"createdAt": "2015-01-12T18:23:02-08:00",
"modifiedAt": "2015-01-12T18:23:02-08:00"
}
],
"commentCount" : 1,
"accessLevel": "OWNER",
"parentType": "ROW",
"parentId": 4508369022150532,
"lastCommentedUser": {
"name": "Test User",
"email": "tester@smartsheet.com"
},
"createdBy": {
"name": "Test User",
"email": "tester@smartsheet.com"
},
"readOnly": false,
"lastCommentedAt": "2015-01-12T18:23:02-08:00"
}
]
}
GET /sheets/{sheetId}/discussions
Gets a list of all discussions associated with the specified sheet. Remember that discussions are containers for the conversation thread. To see the entire thread, use the include=comments parameter.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | include (optional) -- a comma-separated list of optional elements to include in the response:
|
Returns | IndexResult object containing an array of Discussion objects |
Access Scope | READ_SHEETS |
Get Discussion
Example request: get discussion
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 2252168947361668,
discussionId: 2331373580117892
};
// Get discussion
smartsheet.sheets.getDiscussions(options)
.then(function(discussion) {
console.log(discussion);
})
.catch(function(error) {
console.log(error);
});
Discussion discussion = smartsheet.SheetResources.DiscussionResources.GetDiscussion(
9283173393803140, // sheetId
0123456789012345 // discussionId
);
Discussion discussion = smartsheet.sheetResources().discussionResources().getDiscussion(
9283173393803140L, // long sheetId
0123456789012345L // long discussionId
);
discussion = smartsheet_client.Discussions.get_discussion(
9283173393803140, # sheet_id
0123456789012345) # discussion_id
# discussion is an instance of smartsheet.models.Discussion
discussion = smartsheet.sheets.discussions.get(
sheet_id: 4583173393803140,
discussion_id: 3962273862576004
)
Example response
{
"title": "This is a new discussion",
"id": 2331373580117892,
"comments": [
{
"id": 2331373580117892,
"text": "This text is the body of the discussion",
"createdBy": {
"email": "john.doe@smartsheet.com"
},
"modifiedAt": "2012-07-25T00:02:42-07:00"
}
],
"commentCount" : 1
}
GET /sheets/{sheetId}/discussions/{discussionId}
Gets the discussion specified in the URL.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Discussion object |
Access Scope | READ_SHEETS |
List Row Discussions
Example request: list row discussions
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions?include=comments,attachments' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
// Set options
var options = {
sheetId: 2252168947361668,
rowId: 4293147074291588
};
// List row discussions
smartsheet.sheets.getRowDiscussions(options)
.then(function(discussionList) {
console.log(discussionList);
})
.catch(function(error) {
console.log(error);
});
// Sample 1: Omit 'include' parameter and pagination parameters
PaginatedResult<Discussion> results = smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(
2252168947361668, // sheetId
4293147074291588, // rowId
null, // IEnumerable<DiscussionInclusion> include
null // PaginationParameters
);
// Sample 2: Specify 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true'
PaginatedResult<Discussion> results = smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(
2252168947361668, // sheetId
4293147074291588, // rowId
new DiscussionInclusion[] { DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS },
new PaginationParameters(
true, // includeAll
null, // int pageSize
null) // int page
);
// Sample 1: Omit 'include' parameter and pagination parameters
PagedResult<Discussion> results = smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(
2252168947361668L, // long sheetId
4293147074291588L, // long rowId
null, // PaginationParameters
null // EnumSet<DiscussionInclusion> includes
);
// Sample 2: Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters()
.setIncludeAll(true);
// Get all row discussions (specify 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true')
PagedResult<Discussion> results = smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(
2252168947361668L, // long sheetId
4293147074291588L, // long rowId
parameters,
EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS)
);
# Sample 1: List all
response = smartsheet_client.Discussions.get_row_discussions(
2252168947361668, # sheet_id
4293147074291588, # row_id
include_all=True)
discussions = response.data
# Sample 2: Paginate the list
response = smartsheet_client.Discussions.get_row_discussions(
2252168947361668, # sheet_id
4293147074291588, # row_id
page_size=10)
pages = response.total_pages # starts on page 1 by default
discussions = response.data
response = smartsheet.sheets.discussions.list_row_discussions(
sheet_id: 4583173393803140,
row_id: 4293147074291588
)
discussions = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 1,
"data": [
{
"id": 3138415114905476,
"title": "Lincoln",
"comments": [
{
"id": 7320407591151492,
"text": "16th President",
"createdBy": {
"name": "Test User",
"email": "tester@smartsheet.com"
},
"createdAt": "2015-01-12T18:23:02-08:00",
"modifiedAt": "2015-01-12T18:23:02-08:00"
}
],
"commentCount" : 1,
"accessLevel": "OWNER",
"parentType": "ROW",
"parentId": 4508369022150532,
"lastCommentedUser": {
"name": "Test User",
"email": "tester@smartsheet.com"
},
"createdBy": {
"name": "Test User",
"email": "tester@smartsheet.com"
},
"readOnly": false,
"lastCommentedAt": "2015-01-12T18:23:02-08:00"
}
]
}
GET /sheets/{sheetId}/rows/{rowId}/discussions
Gets a list of all discussions associated with the specified row. Remember that discussions are containers for the conversation thread. To see the entire thread, use the include=comments parameter.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | include (optional) -- a comma-separated list of optional elements to include in the response:
|
Returns | IndexResult object containing an array of Discussion objects |
Access Scope | READ_SHEETS |
Related Items
A discussion is a collection of one or more comments, each of which may contain attachments.
Discussion Attachments
For details about working with the attachments within a discussion, see Attachments.
Discussion Comments
For details about working with a discussion's comments, see Comments.
Favorites
Smartsheet allows users to "star" dashboards, folders, reports, sheets, workspaces, and other objects on their Home tab to mark them as favorites. These API operations allow you to access the user's favorite API-supported objects, as well as create and delete favorites.
Objects
Favorite Object
Example: Favorite object
{
"type": "sheet",
"objectId": 5897312590423940
}
objectId | number | Id of the favorited item. If type is template, only private sheet-type template Id is allowed. |
type | string | One of: folder, report, sheet, sight, template, or workspace |
Add Favorites
Example request: add favorites
curl https://api.smartsheet.com/2.0/favorites \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"type": "sheet", "objectId": 8400677765441412}]'
// Specify favorites
var favorites = [
{
"type": "sheet",
"objectId": 8400677765441412
}
];
// Set options
var options = {
body: favorites
};
// Add items to favorites
smartsheet.favorites.addItemsToFavorites(options)
.then(function(newFavorite) {
console.log(newFavorite);
})
.catch(function(error) {
console.log(error);
});
// Specify favorites
IList<Favorite> favoritesSpecification = new Favorite[]
{
new Favorite
{
Type = ObjectType.SHEET,
ObjectId = 8400677765441412
}
};
// Add items to favorites
IList<Favorite> newFavorite = smartsheet.FavoriteResources.AddFavorites(favoritesSpecification);
// Specify favorites
Favorite favoritesSpecification = new Favorite()
.setObjectId(8400677765441412L)
.setType(FavoriteType.SHEET);
// Add items to favorites
List<Favorite> newFavorite = smartsheet.favoriteResources().addFavorites(Arrays.asList(favoritesSpecification));
response = smartsheet_client.Favorites.add_favorites([
smartsheet.models.Favorite({
'type': 'sheet',
'object_id': 8400677765441412
})
])
# Specify favorites
body = {
type: 'sheet',
object_id: 8400677765441412
}
# Add items to favorites
response = smartsheet.favorites.add(
body: body
)
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": [{
"type": "sheet",
"objectId": 8400677765441412
}]
}
POST /favorites
Adds one or more items to the user's list of favorite items. This operation supports both single-object and bulk semantics. For more information, see Optional Bulk Operations.
If called with a single Favorite object, and that favorite already exists, error code 1129 is returned. If called with an array of Favorite objects, any objects specified in the array that are already marked as favorites are ignored and omitted from the response.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | Favorite object or an array of Favorite objects, with the following attributes:
|
Returns | Result object containing objects that were marked as favorites -- either a single Favorite object or an array of Favorite objects, corresponding to what was specified in the request. |
Access Scope | ADMIN_WORKSPACES |
List Favorites
Example request: list favorites
curl https://api.smartsheet.com/2.0/favorites \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
smartsheet.favorites.listFavorites()
.then(function(favoritesList) {
console.log(favoritesList);
})
.catch(function(error) {
console.log(error);
});
// Omit pagination parameters
PaginatedResult<Favorite> results = smartsheet.FavoriteResources.ListFavorites(
null // PaginationParameters
);
// Omit pagination parameters
PagedResult<Favorite> results = smartsheet.favoriteResources().listFavorites(
null // PaginationParameters
);
response = smartsheet_client.Favorites.list_favorites(include_all=True)
faves = response.data
response = smartsheet.favorites.list
list = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [
{
"type": "sheet",
"objectId": 5897312590423940
},
{
"type": "folder",
"objectId": 1493728255862660
}
]
}
GET /favorites
Gets a list of all of the user's favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. |
Returns | IndexResult object containing an array of Favorite objects |
Access Scope | READ_SHEETS |
Remove Favorite
Remove Favorite Folder
Example request: remove favorite folder
curl https://api.smartsheet.com/2.0/favorites/folder/{folderId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
objectId: 2252168947361668
};
// Remove folder from list of favorites
smartsheet.favorites.removeFolderFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.FOLDER,
new long[] { 2252168947361668 } // folderId
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.FOLDER,
new HashSet(Arrays.asList(2252168947361668L)) // long folderId
);
smartsheet_client.Favorites.remove_favorites(
'folder',
2252168947361668 # folder_id
)
smartsheet.favorites.remove_folder(
folder_id: 2252168947361668
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/folder/{folderId}
Removes a single folder from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Favorite Report
Example request: remove favorite report
curl https://api.smartsheet.com/2.0/favorites/report/{reportId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
objectId: 2252168947361668
};
// Remove report from list of favorites
smartsheet.favorites.removeReportFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.REPORT,
new long[] { 2252168947361668 } // reportId
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.REPORT,
new HashSet(Arrays.asList(2252168947361668L)) // long reportId
);
smartsheet_client.Favorites.remove_favorites(
'report',
2252168947361668 # report_id
)
smartsheet.favorites.remove_report(
report_id: 2252168947361668
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/report/{reportId}
Removes a single report from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Favorite Sheet
Example request: remove favorite sheet
curl https://api.smartsheet.com/2.0/favorites/sheet/{sheetId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
objectId: 2252168947361668
};
// Remove sheet from list of favorites
smartsheet.favorites.removeSheetFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.SHEET,
new long[] { 2252168947361668 } // sheetId
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.SHEET,
new HashSet(Arrays.asList(2252168947361668L)) // long sheetId
);
smartsheet_client.Favorites.remove_favorites(
'sheet',
2252168947361668 # sheet_id
)
smartsheet.favorites.remove_sheet(
sheet_id: 2252168947361668
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/sheet/{sheetId}
Removes a single sheet from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Favorite Dashboard
Example request: remove favorite dashboard
curl https://api.smartsheet.com/2.0/favorites/sight/{sightId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
objectId: 6327127650920324
};
// Remove dashboard from list of favorites
smartsheet.favorites.removeSightFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.SIGHT,
new long[] { 2252168947361668 } // sightId
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.SIGHT,
new HashSet(Arrays.asList(2252168947361668L)) // long sightId
);
smartsheet_client.Favorites.remove_favorites(
'sight',
6327127650920324 # sight_id
)
smartsheet.favorites.remove_sight(
sight_id: 6327127650920324
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/sights/{sightId}
Removes a single dashboard from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Favorite Template
Example request: remove favorite template
curl https://api.smartsheet.com/2.0/favorites/template/{templateId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
objectId: 2252168947361668
};
// Remove template from list of favorites
smartsheet.favorites.removeTemplateFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.TEMPLATE,
new long[] { 2252168947361668 } // templateId
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.TEMPLATE,
new HashSet(Arrays.asList(2252168947361668L)) // long templateId
);
smartsheet_client.Favorites.remove_favorites(
'template',
2252168947361668 # template_id
)
smartsheet.favorites.remove_template(
template_id: 2252168947361668
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/template/{templateId}
Removes a single template from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Favorite Workspace
Example request: remove favorite workspace
curl https://api.smartsheet.com/2.0/favorites/workspace/{workspaceId} \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
objectId: 2252168947361668
};
// Remove workspace from list of favorites
smartsheet.favorites.removeWorkspaceFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.WORKSPACE,
new long[] { 2252168947361668 } // workspaceId
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.WORKSPACE,
new HashSet(Arrays.asList(2252168947361668L)) // long workspaceId
);
smartsheet_client.Favorites.remove_favorites(
'workspace',
2252168947361668 # workspace_id
)
smartsheet.favorites.remove_workspace(
workspace_id: 2252168947361668
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/workspace/{workspaceId}
Removes a single workspace from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Multiple Favorites
Remove Multiple Favorite Folders
Example request: remove multiple favorite folders
curl 'https://api.smartsheet.com/2.0/favorites/folder?objectIds=folderId1,folderId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
queryParameters: {
objectIds: "2252168947361668,2252168947361669"
}
};
// Remove folders from list of favorites
smartsheet.favorites.removeFoldersFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.FOLDER,
new long[] { 2252168947361668, 2252168947361669 } // folderIds
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.FOLDER,
new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L)) // long folderIds
);
smartsheet_client.Favorites.remove_favorites(
'folder',
[2252168947361668, 2252168947361669] # folder_ids
)
smartsheet.favorites.remove_folders(
folder_ids: [2252168947361668, 2252168947361669]
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/folder
Removes multiple folders from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Multiple Favorite Reports
Example request: remove multiple favorite reports
curl 'https://api.smartsheet.com/2.0/favorites/report?objectIds=reportId1,reportId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
queryParameters: {
objectIds: "2252168947361668,2252168947361669"
}
};
// Remove reports from list of favorites
smartsheet.favorites.removeReportsFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.REPORT,
new long[] { 2252168947361668, 2252168947361669 } // reportIds
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.REPORT,
new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L)) // long reportIds
);
smartsheet_client.Favorites.remove_favorites(
'report',
[2252168947361668, 2252168947361669] # report_ids
)
smartsheet.favorites.remove_reports(
report_ids: [2252168947361668, 2252168947361669]
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/report
Removes multiple reports from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Multiple Favorite Sheets
Example request: remove multiple favorite sheets
curl 'https://api.smartsheet.com/2.0/favorites/sheet?objectIds=sheetId1,sheetId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
queryParameters: {
objectIds: "2252168947361668,2252168947361669"
}
};
// Remove sheets from list of favorites
smartsheet.favorites.removeSheetsFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.SHEET,
new long[] { 2252168947361668, 2252168947361669 } // sheetIds
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.SHEET,
new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L)) // long sheetIds
);
smartsheet_client.Favorites.remove_favorites(
'sheet',
[2252168947361668, 2252168947361669] # sheet_ids
)
smartsheet.favorites.remove_sheets(
sheet_ids: [2252168947361668, 2252168947361669]
)
Example Response:
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/sheet
Removes multiple sheets from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Multiple Favorite Dashboards
Example request: remove multiple favorite dashboards
curl 'https://api.smartsheet.com/2.0/favorites/sight?objectIds=sightId1,sightId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
queryParameters: {
objectIds: '970160371507588,6327427650920324'
}
};
// Remove dashboard from list of favorites
smartsheet.favorites.removeSightsFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.SIGHT,
new long[] { 2252168947361668, 3404239197235076 } // sightIds
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.SIGHT,
new HashSet(Arrays.asList(2252168947361668L, 3404239197235076L)) // long sightIds
);
smartsheet_client.Favorites.remove_favorites(
'sight',
[6327127650920324, 3404239197235076] # sight_ids
)
smartsheet.favorites.remove_sights(
sight_ids: [6327127650920324, 2591554075418573]
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/sights
Removes multiple dashboards from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Multiple Favorite Templates
Example request: remove multiple favorite templates
curl 'https://api.smartsheet.com/2.0/favorites/template?objectIds=templateId1,templateId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
queryParameters: {
objectIds: "2252168947361668,2252168947361669"
}
};
// Remove templates from list of favorites
smartsheet.favorites.removeTemplatesFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.TEMPLATE,
new long[] { 2252168947361668, 2252168947361669 } // templateIds
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.TEMPLATE,
new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L)) // long templateIds
);
smartsheet_client.Favorites.remove_favorites(
'template',
[2252168947361668, 2252168947361669] # template_ids
)
smartsheet.favorites.remove_templates(
template_ids: [2252168947361668, 2252168947361669]
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/template
Removes multiple templates from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Remove Multiple Favorite Workspaces
Example request: remove multiple favorite workspaces
curl 'https://api.smartsheet.com/2.0/favorites/workspace?objectIds=workspaceId1,workspaceId2' \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X DELETE
// Set options
var options = {
queryParameters: {
objectIds: "2252168947361668,2252168947361669"
}
};
// Remove workspaces from list of favorites
smartsheet.favorites.removeWorkspacesFromFavorites(options)
.then(function(results) {
console.log(results);
})
.catch(function(error) {
console.log(error);
});
smartsheet.FavoriteResources.RemoveFavorites(
ObjectType.WORKSPACE,
new long[] { 2252168947361668, 2252168947361669 } // workspaceIds
);
smartsheet.favoriteResources().removeFavorites(
FavoriteType.WORKSPACE,
new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L)) // long workspaceIds
);
smartsheet_client.Favorites.remove_favorites(
'workspace',
[2252168947361668, 2252168947361669] # workspace_ids
)
smartsheet.favorites.remove_workspaces(
workspace_ids: [2252168947361668, 2252168947361669]
)
Example response
{
"message": "SUCCESS",
"resultCode": 0
}
DELETE /favorites/workspace
Removes multiple workspaces from the user's list of favorite items.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | objectIds (required): a comma-separated list of object Ids representing the items to remove from favorites |
Returns | Result object |
Access Scope | ADMIN_WORKSPACES |
Folders
A folder can exist in a user's Sheets folder (Home), in a folder, or in a workspace.
Objects
Folder Object
Example: Folder object
{
"id": 7116448184199044,
"name": "Projects",
"permalink": "https://app.smartsheet.com/b/home?lx=B0_lvAtnWygeMrWr4Rfoa",
"sheets": []
}
id | number | Folder Id |
favorite | Boolean | Returned only if the user has marked the folder as a favorite in their "Home" tab (value = true) |
folders | Folder[] | Array of Folder objects |
name | string | Folder name |
permalink | string | URL that represents a direct link to the folder in Smartsheet |
reports | Report[] | Array of Report objects |
sheets | Sheet[] | Array of Sheet objects |
sights | Dashboard[] | Array of Dashboard objects |
templates | Template[] | Array of Template objects |
Copy Folder
Example request: copy folder
curl 'https://api.smartsheet.com/2.0/folders/{folderId}/copy?include=data'
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
-H "Content-Type: application/json"
-d '{
"destinationType": "folder",
"destinationId": 7960873114331012,
"newName": "newFolderName"
}'
-X POST
// Specify destination information
var body = {
destinationType: "folder",
destinationId: 7960873114331012,
newName: "Folder Copy"
};
// Specify elements to copy
var params = {
include: "data,discussions",
skipRemap: "cellLinks"
};
// Set options
var options = {
folderId: 2252168947361668,
body: body,
queryParameters: params
};
// Copy folder
smartsheet.folders.copyFolder(options)
.then(function(folder) {
console.log(folder);
})
.catch(function(error) {
console.log(error);
});
// Specify destination
ContainerDestination destination = new ContainerDestination {
DestinationId = 7960873114331012,
DestinationType = DestinationType.FOLDER,
NewName = "newFolderName"
};
// Sample 1: Omit 'include' and 'skipRemap' parameters
Folder folder = smartsheet.FolderResources.CopyFolder(
2252168947361668, // long folderId
destination,
null, // IEnumerable<FolderCopyInclusion> include
null // IEnumerable<FolderRemapExclusion> skipRemap
);
// Sample 2: Specify 'include' parameter with value of "DATA", and 'skipRemap' parameter with value of "CELL_LINKS"
Folder folder = smartsheet.FolderResources.CopyFolder(
2252168947361668, // long folderId
destination,
new FolderCopyInclusion[] {
FolderCopyInclusion.DATA },
new FolderRemapExclusion[] {
FolderRemapExclusion.CELL_LINKS }
);
// Specify destination
ContainerDestination destination = new ContainerDestination()
.setDestinationType(DestinationType.FOLDER)
.setDestinationId(7960873114331012L)
.setNewName("newFolderName");
// Sample 1: Omit 'include' and 'skipRemap' parameters
Folder folder = smartsheet.folderResources().copyFolder(
2252168947361668L, // long folderId
destination,
null, // EnumSet<FolderCopyInclusion> includes
null // EnumSet<FolderRemapExclusion> skipRemap
);
// Sample 2: Specify 'include' parameter with value of "DATA", and 'skipRemap' parameter with value of "CELLLINKS"
Folder folder = smartsheet.folderResources().copyFolder(
2252168947361668L, // long folderId
destination,
EnumSet.of(FolderCopyInclusion.DATA),
EnumSet.of(FolderRemapExclusion.CELLLINKS)
);
response = smartsheet_client.Folders.copy_folder(
2252168947361668, # folder_id
smartsheet.models.ContainerDestination({
'destination_id': 7960873114331012,
'destination_type': 'folder',
'new_name': 'newFolderName'
})
)
# Specify destination information
body = {
destination_type: 'folder',
destination_id: 7960873114331012,
new_name: 'newFolderName'
}
# Copy folder
response = smartsheet.folders.copy(
folder_id: 2252168947361668,
body: body
)
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 7116448184199044,
"name": "newFolderName",
"permalink": "https://{base_url}?lx=lB0JaOh6AX1wGwqxsQIMaA"
}
}
POST /folders/{folderId}/copy
Creates a copy of the specified folder.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Parameters | include (optional) -- comma-separated list of elements to copy:
|
skipRemap (optional) -- comma-separated list of references to NOT re-map for the newly created folder:
|
|
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:
|
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:
|
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:
|
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:
|
Returns | Folder object, populated according to the include parameter NOTE: If no dashboards, folders, reports, sheets, or templates are present in the folder, the corresponding attribute (for example, folders, sheets) is not present in the response. |
Access Scope | READ_SHEETS |
List Folders
Gets a list of top-level child folders from the user's Sheets folder (Home), from another folder, or from a workspace.
List Folders (Sheet Level)
Example request: list folders (sheet level)
curl https://api.smartsheet.com/2.0/home/folders \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json"
smartsheet.home.listFolders()
.then(function(folderList) {
console.log(folderList);
})
.catch(function(error) {
console.log(error);
})
// Omit pagination parameters
PaginatedResult<Folder> folders = smartsheet.HomeResources.FolderResources.ListFolders(
null // PaginationParameters
);
// Omit pagination parameters
PagedResult<Folder> folders = smartsheet.homeResources().folderResources().listFolders(
null // PaginationParameters
);
# Sample 1: List all
response = smartsheet_client.Home.list_folders(include_all=True)
home_sheets_folders = response.data
# Sample 2: Paginate the list
response = smartsheet_client.Home.list_folders(
page_size=5,
page=1)
pages = response.total_pages
folders = response.data
response = smartsheet.folders.list
folders = response[:data]
Example response
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [
{
"id": 9116888184199044,
"name": "Folder 1",
"permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
},
{
"id": 225255547361668,
"name": "Folder 2",
"permalink": "https://app.smartsheet.com/b/home?lx=xgDVrNNbi-O9XwINEpT5Er"
}
]
}
GET /home/folders
Gets a list of the top-level child folders within the user's Sheets folder (Home).
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 |
Parameters | This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters. |
Returns | IndexResult object containing an array of Folder objects, limited to the following attributes:
|
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:
|
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:
|
Access Scope | READ_SHEETS |
Move Folder
Example request: move folder
curl https://api.smartsheet.com/2.0/folders/{folderId}/move \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-d '{
"destinationType": "folder",
"destinationId": 7960873114331012
}' \
-X POST
// Set destination information
var body = {
destinationType: "folder",
destinationId: 7960873114331012
};
// Set options
var options = {
folderId: 4509918431602564,
body: body
};
// Move folder
smartsheet.folders.moveFolder(options)
.then(function(folder) {
console.log(folder);
})
.catch(function(error) {
console.log(error);
});
// Specify destination
ContainerDestination destination = new ContainerDestination {
DestinationId = 7960873114331012, // long destinationFolderId
DestinationType = DestinationType.FOLDER,
};
// Move folder
Folder folder = smartsheet.FolderResources.MoveFolder(
4509918431602564, // long folderId
destination
);
// Specify destination
ContainerDestination destination = new ContainerDestination()
.setDestinationType(DestinationType.FOLDER)
.setDestinationId(7960873114331012L);
// Move folder
Folder folder = smartsheet.folderResources().moveFolder(
4509918431602564L, // long folderId
destination
);
folder = smartsheet_client.Folders.move_folder(
4509918431602564, # folder_id to be moved
smartsheet.models.ContainerDestination({
'destination_id': 7960873114331012, # destination folder_id
'destination_type': 'folder'
})
)
# Specify destination information
body = {
destination_type: 'workspace',
destination_id: 7960873114331012
}
# Move folder
response = smartsheet.folders.move(
folder_id: 4509918431602564,
body: body
)
Example response
{
"message": "SUCCESS",
"resultCode": 0,
"result": {
"id": 4509918431602564,
"name": "moved_folder_name",
"permalink": "https://{base_url}?lx=lB0JaOh6AX1wGwqxsQIMaA"
}
}
POST /folders/{folderId}/move
Moves the specified folder to another location.
Headers | Authorization: Bearer ll352u9jujauoqz4gstvsae05 Content-Type: application/json |
Request Body | ContainerDestination object, limited to the following required attributes:
|
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 =