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