Smartsheet API 2.0

Updated 2017-07-19

Overview

Introduction

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

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

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

  • Read and update sheets
  • Manage folders and workspaces
  • Administer users and accounts

You can view code examples in the programming language of your choice by clicking the corresponding tab in the dark-blue area in the rightmost pane.

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:

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 Sample Code and SDKs.

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 the user to make API calls. The email address used to identify the user must be URI-encoded. jane.doe%40smartsheet.com

Query Strings

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

Query String Type Description More Info
pageSize Number Specifies the maximum number of items to return per page, for example, pageSize=25. Paging
page String Specifies which page to return, for example, page=4. Paging
includeAll Boolean If true, includes all results, for example, includeAll=true. Paging
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
numericDates Boolean If true, allows you to input or receive dates in numeric format, for example, numericDates=true. Dates and Times
include/exclude String When applicable for a specific object, various include or exclude parameters are available, for example, include=formatting. Object reference or Formatting

Authentication and Access Tokens

Example Request: Authentication and Access Tokens

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

Example Response:

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

The Smartsheet API uses OAuth 2.0 for Authentication and Authorization. An HTTP header containing an Access Token is required to authenticate each request.

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

  1. Open the Account/Personal Settings form and click the “API Access” tab.
  2. 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. 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 flag 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 Sheets folder (Home), in a Folder, or in a Workspace. It is comprised of Columns, Rows, and Cells, and may optionally contain Attachments and/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 and/or Discussions. Row Object
Cell A Cell is a location within a Sheet that may contain a value. A collection of Cells comprises each Row in a Sheet. Cell Object, Cell reference

Versioning and Changes

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

Getting Started

Make Your First API Call

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

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

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

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

In Postman, the request looks like this:

Postman screen shot

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

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

How to Read a Sheet Response

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

Basic sheet with 2 rows and 2 columns

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

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

    Image of the Sheet Properties window

  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"

  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 connects column title to Id 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,                  // You must 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 us this is the "Name" column
                    "value": "John Doe",            // Actual cell value
                    "displayValue": "John Doe"      // How the cell value is displayed in the UI
                },
                {
                    "columnId": 7020703884044164,
                    "value": 12345,                 
                    "displayValue": "12345"
                }
            ]
        },
        {
            "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.

Sample Code and SDKs

Smartsheet has 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

Submit your vote for additional language coverage by sending email to api@smartsheet.com.

Other Topics

Access Levels

Sheets, Workspaces, and Templates 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.

Third-party App Development

In addition to being a powerful work management tool, Smartsheet is a powerful application platform.

As a developer, you may be building applications that allow any Smartsheet user to access his or her Smartsheet data. The following sub-sections describe next steps.

Developer Registration

Third-party app registration and management is available via the Developer Tools. To get access to Developer Tools, you must first register as a Smartsheet developer. Follow the instructions on the registration form to add Developer Tools to an existing Smartsheet account or create a new Smartsheet developer account.

Once you complete the developer registration, log in to Smartsheet to access Developer Tools.

  1. Click the Account button in the upper-left corner of your Smartsheet screen.
  2. Now that you are registered as a Smartsheet developer, click the new Developer Tools option in the dropdown menu to open Developer Tools.
  3. Before you can register your first app, you must complete your developer profile. Developer profile is a public profile that anyone can access to learn more about you and your applications.
  4. Once your developer profile is complete, you can use Developer Tools to register and manage your apps.

Register Your App

To build a third-party app, you must first register it with Smartsheet using Developer Tools:

  1. Login to Smartsheet.
  2. Click the Account button in the upper-left corner of your Smartsheet screen and click Developer Tools.
  3. Create new app and provide the required information, including name, description, contact info and a redirect URL. Redirect URL (also known as the “callback URL”) is the URL in your app where Smartsheet must redirect after authentication is complete.
  4. Use the generated app client id and secret to connect your app to Smartsheet. See OAuth Flow for details on how to use client id and secret to do that.

Access Scopes

To access an end user’s Smartsheet data, your application must explicitly ask for specific Access Scopes. The Access Scopes enable your app to communicate to the end users 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 end 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 Sight structure.
ADMIN_USERS Add and remove users from your Smartsheet organization; create groups and manage membership.
ADMIN_WEBHOOKS Create, delete. and update webhooks; get all webhooks; reset shared secret.
ADMIN_WORKSPACES Create and manage workspaces and folders, including sharing.
CREATE_SHEETS Create new sheets.
CREATE_SIGHTS Create new Sights.
DELETE_SHEETS Delete sheets.
DELETE_SIGHTS Delete Sight.
READ_CONTACTS Retrieve contacts.
READ_SHEETS Read all sheet data, including attachments, discussions, and cell data.
READ_SIGHTS Read all Sight data.
READ_USERS Retrieve users and groups for your Smartsheet organization.
SHARE_SHEETS Share sheets, including sending sheets as attachments.
SHARE_SIGHTS Share Sight.
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 that can be used to access Smartsheet data on behalf of an end user. The following sub-sections describe next steps.

Request Authorization From the User

To request authorization from an end user, direct your user to https://app.smartsheet.com/b/authorize with the following parameters through either a GET or POST. The parameter values must be URL-encoded:

Value Description
response_type
(required)
Must be set to “code”.
client_id
(required)
Client Id for your app.
redirect_uri
(optional)
Redirect URL you registered for your app (including protocol, for example, “http://”); if not provided, the redirect URL set during registration is used.
scope
(required)
Space-delimited list of access scopes to which you are asking the user to grant access (note the spaces must be URL-encoded as “%20”).
state
(optional)
Arbitrary string returned to your app; intended to be used by you to ensure that this redirect is indeed from an OAuth flow that you initiated.

Here is an example of a URL to which you would send your user as a GET request:

https://app.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE

If your user has not logged in to Smartsheet, he/she will first be directed to the Smartsheet login page. After a successful login, Smartsheet prompts your user to allow or deny the access scopes you requested.

Obtain the Authorization Code

During the above steps for requesting authorization from the user, if the user clicks “Allow”, Smartsheet redirects the user to the redirect_uri with the following parameters:

Value Description
code Authorization code required to obtain access token.
expires_in Number of seconds code is valid once issued; this is always four minutes - you must obtain an access token within that time.
state state string specified earlier.

If the user clicks “Deny”, Smartsheet redirects the user to the redirect_uri with the following parameters:

Value Description
error “access_denied”.
state state string specified earlier.

Other errors that may be returned include:

Value Description
unsupported_response_type response_type must be set to “code”.
invalid_scope One or more of the requested access scopes are invalid. Please check the list of access scopes.

Obtain 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}&redirect_uri={redirect_uri}&hash={SHA_256(app_secret|code)}' \
-X POST

Successful Response:

{
   "ll352u9jujauoqz4gstvsae05": "Access Token Value",
   "token_type": "bearer",
   "refresh_token": "Refresh Token Value",
   "expires_in": "# of seconds before token expires"
}

Error Response:

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

Once you’ve successfully obtained an authorization code, the next step is to obtain an access token. To do so, make a POST request to https://api.smartsheet.com/2.0/token with the following parameters:

Value Description
grant_type
(required)
Must be set to “authorization_code”.
client_id
(required)
Client Id for your app.
code
(required)
Authorization code returned in the previous step.
redirect_uri
(optional)
Redirect URL registered for your app, including the protocol (for example, “http://”); if not provided, the redirect URL set during registration is used.
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. To obtain an app_secret, see Register Your App.

Reminder: you can see what a success call looks like in the dark-blue area in the rightmost pane.

Possible OAuth error types:

Value Description
invalid_request The request parameters are invalid or missing.
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, the redirect_uri does not match, or the hash value does not match the app secret and/or code.
unsupported_grant_type grant_type must equal “authorization_code” or “refresh_token”.

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}&redirect_uri={redirect_uri}&hash={SHA_256(app_secret|refresh_token)}' \
-X POST

Successful Response:

{
   "1": "Newly refreshed Access Token",
   "expires_in": "# of seconds before token expires",
   "token_type": "bearer",
   "refresh_token": "New refresh token"
}

Access tokens expire after 7 days. Use the refresh token to obtain a new access token. Once you obtain the new access token, you must use it in place of the old one, which is no longer valid.

To do so, make a POST request to https://api.smartsheet.com/2.0/token with the following parameters:

Value Description
grant_type
(required)
Must be set to “refresh_token”.
client_id
(required)
Client Id for your app.
refresh_token
(required)
refresh_token value that came with the access token.
redirect_uri
(optional)
Redirect URL registered for your app, including the protocol (for example, “http://”).
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.

Get Basic User Info

Once you have obtained an access token on behalf of the user, you can fetch basic information (including user Id, name, etc.) about the caller using the Get Current User operation.

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

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

Value Type Description
pageSize number The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100 if not 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.
includeAll Boolean If true, include all results, that is, do not paginate. Mutually exclusive with pageSize and page (they are ignored if includeAll=true is specified).

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:

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.
totalPages number The total number of pages in the full result set.
totalCount number The total number of items in the full result set.
data array An array of objects representing the current page of data in the 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
name string Attachment name
url string Attachment temporary URL (files only)
urlExpiresInMillis number Attachment temporary URL time to live (files only)
attachmentType string Attachment type (one of FILE, GOOGLE_DRIVE, LINK, BOX_COM, DROPBOX, EVERNOTE, EGNYTE, ONEDRIVE)
attachmentSubType string Attachment sub type, valid only for either GOOGLE_DRIVE attachments or EGNYTE attachments:
  • possible values for GOOGLE_DRIVE attachments: DOCUMENT, SPREADSHEET, PRESENTATION, PDF, DRAWING
  • possible values for EGNYTE attachments: FOLDER
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
mimeType string Attachment MIME type (PNG, etc.)
parentType string The type of object the attachment belongs to. One of “SHEET”, “ROW”, or “COMMENT”
parentId number The id of the parent
sizeInKb number The size of the file, if the attachmentType is FILE

Post an Attachment

Like the Smartsheet Web 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 upload a file to a sheet, row, or 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 create a new Comment that contains a single file attachment or to add a new Discussion to a Sheet that contains a single file attachment.

Multipart Uploads

A multipart upload request 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 upload a file using a single request. For example, you can perform a multipart upload to create a new Comment that contains a single file attachment or to add a new Discussion to a Sheet that contains a single file attachment.

A multipart upload request must include the following HTTP headers:

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

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

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

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

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

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

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

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

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

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

Simple Uploads

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

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-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.
Content-Length Must be set to the size of the file, in bytes. For example to determine file size using in UNIX:

$ ls -l ProgressReport.docx
5463 ProgressReport.docx

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 (multipart): Attach File to Comment

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"

Example Request (simple): 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

Example Response:

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

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.

Access Scope WRITE_SHEETS
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

Attach File to Row

Example Request (multipart): Attach File to Row

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"

Example Request (simple): 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

Example Response:

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

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.

Access Scope WRITE_SHEETS
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

Attach File to Sheet

Example Request (multipart): Attach File to Sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"

Example Request (simple): 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

Example Response:

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

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.

Access Scope WRITE_SHEETS
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

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

Example Response:

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

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

Attaches a URL to the Comment.

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

The URL can be any of the following:

  • Normal URL (attachmentType “LINK”)
  • Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • Box.com URL (attachmentType “BOX_COM”)
  • Dropbox URL (attachmentType “DROPBOX”)
  • Evernote URL (attachmentType “EVERNOTE”)
  • Egnyte URL (attachmentType “EGNYTE”)
  • 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"}'

Example Response:

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

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

Attaches a URL to the Row.

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

The URL can be any of the following:

  • Normal URL (attachmentType “LINK”)
  • Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • Box.com URL (attachmentType “BOX_COM”)
  • Dropbox URL (attachmentType “DROPBOX”)
  • Evernote URL (attachmentType “EVERNOTE”)
  • Egnyte URL (attachmentType “EGNYTE”)
  • 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"}'

Example Response:

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

POST /sheets/{sheetId}/attachments

Attaches a URL to the Sheet.

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

The URL can be any of the following:

  • Normal URL (attachmentType “LINK”)
  • Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • Box.com URL (attachmentType “BOX_COM”)
  • Dropbox URL (attachmentType “DROPBOX”)
  • Evernote URL (attachmentType “EVERNOTE”)
  • Egnyte URL (attachmentType “EGNYTE”)
  • 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

Example Response:

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

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

Deletes the Attachment specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Get Attachment

Example Request: Get Attachment

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

Example Response:

{
    "name": "at3.png",
    "url": "URL_TO_ATTACHMENT",
    "attachmentType": "FILE",
    "mimeType": "image/png",
    "id": 4583173393803140,
    "urlExpiresInMillis": 120000
}

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

Fetches the Attachment specified in the URL.

Access Scope READ_SHEETS
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.

List Attachments

Example Request: List Attachments

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

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": 4583173393803140,
            "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.

Access Scope READ_SHEETS
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

List Discussion Attachments

Example Request: List Discussion Attachments

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

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": 4583173393803140,
            "parentType" : "COMMENT",
            "parentId" : 684956754834557
        }
    ]
}

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

Gets a list of all Attachments that are in the Discussion.

Access Scope READ_SHEETS
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

List Row Attachments

Example Request: List Row Attachments

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

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": 4583173393803140,
            "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.

Access Scope READ_SHEETS
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

Versioning

Attach New Version

Example Request (multipart): Attach New Version

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"

Example Request (simple): 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

Example Response:

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

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.

Access Scope WRITE_SHEETS
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

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

Example Response:

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

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

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

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

List Versions

Example Request: List Versions

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

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 Attachment Id, in order from newest to oldest.

Access Scope READ_SHEETS
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

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.
value string,
number,
or Boolean
A string, a number or a Boolean value – depending on the cell type and the data in the cell. See Cell Reference.
displayValue string Visual representation of cell contents, as presented to the user in the UI. See Cell Reference.
objectValue ObjectValue Optionally included object representation of the cell’s value. Used for updating predecessor cell values.
formula string The formula for a cell, if set. Note: calculation errors or problems with a formula will not cause the API call to return an error code. Instead, the response will contain the same value as in the UI, such as cell.value = “#CIRCULAR REFERENCE”.
hyperlink Hyperlink A hyperlink to a URL, sheet, or report
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.
overrideValidation Boolean (Admin only) Flag indicating 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.
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.
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.
strict Boolean Set to false to enable lenient parsing. Defaults to true. This attribute can be specified in a request, but is never present in a response. See Cell Value Parsing for more information about using this attribute.
image Image The image that the cell contains.
Only returned if the cell contains an image.

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

Represents a link to a Cell in a different Sheet.

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

Represents a hyperlink to a URL, a Sheet, a Report, or a Sight.

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 or reportId or sightId is non-null), this property contains the permalink to the Sheet, Report, or Sight.
sheetId number If non-null, this hyperlink is a link to the Sheet with this Id.
reportId number If non-null, this hyperlink is a link to the Report with this Id.
sightId number If non-null, this hyperlink is a link to the Sight with this Id.

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 DATE, DATETIME, ABSTRACT_DATETIME, CONTACT, DURATION, or PREDECESSOR_LIST

PredecessorList Object

Example Update Row Request 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.

Predecessor Object

rowId number The Id of the predecessor row
rowNumber number The row number of the predecessor row. Omitted if invalid is true. Read-only.
type string The type of the predecessor. One of FS, FF, SS, or SF.
lag Duration The lag value of this predecessor. Omitted if there is no lag.
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 Web app as “#REF”). Read-only. Omitted if false.
inCriticalPath Boolean True if this predecessor is in the critical path. Read-only.

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
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, minutes) is always positive.
elapsed Boolean If true, indicates this duration represents elapsed time, which ignores non-working time.
weeks number The number of weeks for this duration.
days number The number of days for this duration.
hours number The number of hours for this duration.
minutes number The number of minutes for this duration.
seconds number The number of seconds for this duration.
milliseconds number The number of milliseconds for this duration.

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"

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 3,
    "data": [
        {
            "columnId":642523719853956,
            "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":642523719853956,
            "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":642523719853956,
            "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.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters include (optional): when specified with a value of “columnType”, response includes the columnType attribute for each cell
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

Update Cells

To update the Cells in a Sheet, use the Update Rows operation.

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 cell link 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. An empty cell is always represented by null for all of these attributes.

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 would be “$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. Complex types are represented as strings, formatted as described below:

Column Type Possible Types for Cell.value Returns Cell.displayValue?
TEXT_NUMBER string: free-form text values
number: numeric values
Yes: same as value for strings; for number values, the number with formatting applied.
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.
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.
CHECKBOX Boolean: true if the checkbox is checked, false otherwise.
string: a free-form text value.
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
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
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.

Cell.objectValue is an object representation of a cell’s value and is currently used for adding or updating predecessor cell values. 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.

Cell Value Parsing

The flexibility in cell value data types is a powerful feature in the Smartsheet application, but at the same time, it poses a challenge for an API in terms of parsing. Being too flexible will likely 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 Text 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:

TEXT_NUMBER:

Strict All numeric and text values are valid and are interpreted literally.
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.

PICKLIST:

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

DATE:

Strict The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD).
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.

CONTACT_LIST:

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.
Lenient If the value is a valid email address, Smartsheet handles it the same way as Strict. If not, Smartsheet saves the value as a text value.

CHECKBOX:

Strict Only Boolean values (true or false) are valid.
Lenient Boolean values and string values of 'true’ and “false” are handled the same as Strict. All other values are saved as text values.

DURATION:

Strict Only valid duration strings in the user’s locale are valid. Information on duration strings can be found in the Help Center.
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.

PREDECESSOR:

The Smartsheet API doesn’t support parsing of predecessor strings, so strict and lenient parsing don’t apply to predecessors. Instead, you can set the objectValue attribute to a PredecessorList Object containing Predecessor Objects. To set a cell in a predecessor column to a non-predecessor string value, simply set objectValue to a string.

ABSTRACT_DATETIME:

Strict The value must be a string value and a valid ISO 8601 date and time.
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.

Contact List Columns

With columns of type CONTACT_LIST, cells’ “value” and “displayValue” attributes 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.

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
width number Original width (in pixels) of the uploaded image
height number Original height (in pixels) of the uploaded image
altText string Alternate Text for the image

ImageUrl Object

Example ImageUrl Object:

{
    "imageId": "e1znCxhuZo_soEJtUmmX_A",
    "url": "https://urltoimage1.com?qs1=foo"
}
imageId string Image Id
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.)
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.
error Error Error Object. Present in the Get All Image URLs response only if an error occurred retrieving the image.

ImageUrlMap Object

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

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: application/jpeg" \
-H 'Content-Disposition: attachment; filename="picture.jpg"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @picture.jpg

Example Response:

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

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

Uploads an image to the specified Cell within a Sheet.

Access Scope WRITE_SHEETS
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

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

Example Response:

{
    "urlExpiresInMillis": 1800000,
    "imageUrls":  [
        {
            "imageId": "e1znCxhuZo_soEJtUmmX_A",
            "url": "https://urltoimage1.com?qs1=foo"
        },
        {
            "imageId": "g2jdKdfhQa_abKJmPnhC_B",
            "error": {
                "errorCode": 5001,
                "message": "localized_error_message"
            }
        }
    ]
}  

POST /imageurls

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

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

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,
    "index": 0,
    "symbol": "STAR",
    "title": "Favorite",
    "type": "CHECKBOX",
    "validation": false
}
id number Column Id
index number Column index
title string Column title
primary Boolean Returned only if the column is the Primary Column (value = true)
type string One of:
  • TEXT_NUMBER
  • DATE
  • DATETIME
  • CONTACT_LIST
  • CHECKBOX
  • PICKLIST
  • DURATION
  • PREDECESSOR
  • ABSTRACT_DATETIME
See Column Types.
options string[] Array of the options available for the column
contactOptions ContactOption[] Array of ContactOption Objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST
hidden Boolean Flag indicating whether the column is hidden
symbol string When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns.
systemColumnType string When applicable, one of:
  • AUTO_NUMBER
  • MODIFIED_DATE
  • MODIFIED_BY
  • CREATED_DATE
  • CREATED_BY
See System Columns.
autoNumberFormat AutoNumberFormat Present when systemColumnType == AUTO_NUMBER
tags string[] Set of tags to indicate special columns. Each element in the array is set to one of the following values:
  • CALENDAR_START_DATE
  • CALENDAR_END_DATE
  • GANTT_START_DATE
  • GANTT_END_DATE
  • GANTT_PERCENT_COMPLETE
  • GANTT_DISPLAY_LABEL
  • GANTT_PREDECESSOR
  • GANTT_DURATION
  • GANTT_ASSIGNED_RESOURCE
validation Boolean Flag indicating whether validation has been enabled for the column (value = true)
width number Display width of the column in pixels
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.
filter Filter The filter applied to the column.
Only returned if the include query string parameter contains filters and this column has a filter applied to it.
locked Boolean Flag indicating 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 Flag indicating whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.

ContactOption Object

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

Criteria Object

operator string One of the following values:
  • EQUAL
  • NOT_EQUAL
  • GREATER_THAN
  • LESS_THAN
  • CONTAINS
  • BETWEEN
  • TODAY
  • PAST
  • FUTURE
  • LAST_N_DAYS
  • NEXT_N_DAYS
  • IS_BLANK
  • IS_NOT_BLANK
  • IS_NUMBER
  • IS_NOT_NUMBER
  • IS_DATE
  • IS_NOT_DATE
  • IS_CHECKED
  • IS_NOT_CHECKED
value1 string or number Optional. Present if a custom filter criteria’s operator has one or more arguments.
value2 string or number Optional. Present if a custom filter criteria’s operator has two arguments.

Filter Object

Smartsheet users can define and save personal column filters on sheets they can view. When any API operation that returns columns is invoked with the “include=filters” query string parameter, the column includes any active filters the user has defined for the sheet.

type string One of the following values:
  • LIST
  • CUSTOM
excludeSelected Boolean If true, rows containing cells matching the “values” or “criteria” items are excluded instead of included.
values object[] containing strings, numbers, and Booleans Only included if the filter is of type LIST.

An array of literal cell values that this filter matches against row cells in this column. The type of the objects in the array depend on the type of the cell values selected to be filtered on when the filter was created. These may be strings, numbers, Booleans, or dates.
criteria Criteria[] Only included if the filter is of type CUSTOM.

An array of Criteria Objects specifying custom criteria against which to match cell values.

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

Example Response:

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

POST /sheets/{sheetId}/columns

Inserts one or more columns into the Sheet specified in the URL.

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

Delete Column

Example Request: Delete Column

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

Example Response:

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

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

Deletes the Column specified in the URL.

Access Scope ADMIN_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Get Column

Example Request: Get Column

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

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.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters include (optional): when specified with a value of “filters”, response includes the Filter that the user has applied to the column (if any)
Returns Column Object

List Columns

Example Request: List Columns

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

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.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters include (optional): when specified with a value of “filters”, response includes the Filter that the user has applied to each column (if any)

This operation supports query string parameters for pagination of results. For more information, see Paging Query String Parameters.
Returns IndexResult Object containing an array of Column Objects

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

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.

    Access Scope ADMIN_SHEETS
    Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
    Content-Type: application/json
    Request Body A Column object that contains the following attributes:
    • index (column’s new index in the sheet)
    • title
    • type (optional)
    • options (optional)
    • symbol (optional)
    • systemColumnType (optional)
    • autoNumberFormat (optional)
    • validation (optional)
    • width (optional)
    • format (optional)
    • locked (optional)
    Returns Result object containing the Column object that was modified

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
Text/Number TEXT_NUMBER
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.
Date DATE
Dropdown List PICKLIST Custom, RYG, Harvey Ball, Priority types, etc.
Checkbox CHECKBOX Checkbox, star, and flag types
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 Only for dependency-enabled project sheets
The API does not support setting a Column to this type, or updating data in a column of this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.)
Date/Time ABSTRACT_DATETIME Represents a project sheet’s Start and End dates.
Only for dependency-enabled project sheets
The API does not support setting a Column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) Additionally, the API does not support updating data in the End Date column under any circumstance, and does not support updating data in the Start Date column if Predecessor is set for that row.
Date/Time DATETIME Used only by the following System-generated columns:
  • Created (Date) (Column.systemColumnType = “CREATED_DATE”)
  • Modified (Date) (Column.systemColumnType = “MODIFIED_DATE”)

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 PICKLIST or CHECKBOX, whose symbol attribute is set to one of the values below:

Symbols for CHECKBOX columns:

Value Example
FLAG A flag symbol
STAR A star symbol

Symbols for PICKLIST columns:

Value Example
ARROWS_3_WAY An arrows_3_way symbol
ARROWS_4_WAY An arrows_4_way symbol
ARROWS_5_WAY An arrows_5_way symbol
DECISION_SHAPES A decision_shapes symbol
DECISION_SYMBOLS A decision_symbols symbol
DIRECTIONS_3_WAY A directions_3_way symbol
DIRECTIONS_4_WAY A directions_4_way symbol
EFFORT An effort symbol
HARVEY_BALLS A harvey_balls symbol
HEARTS A hearts symbol
MONEY A money symbol
PAIN A pain symbol
PRIORITY A priority symbol
PRIORITY_HML A priority_hml symbol
PROGRESS A progress symbol
RYG An RYG symbol
RYGB An RYGB symbol
RYGG An RYGG symbol
SIGNAL A signal symbol
SKI A ski symbol
STAR_RATING A star_rating symbol
VCR A VCR symbol
WEATHER A weather symbol

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
MODIFIED_DATE DATETIME
MODIFIED_BY CONTACT_LIST
CREATED_DATE DATETIME
CREATED_BY CONTACT_LIST
AUTO_NUMBER TEXT_NUMBER Columns of this system column type include an AutoNumberFormat Object that describes the mask used to generate the value.

Comments

A Comment is a component of a Discussion. Each Discussion is composed of one or more 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
text string Comment body
createdBy User User Object containing name and email of the Comment’s author
createdAt timestamp Time of creation
modifiedAt timestamp Time of last modification
attachments Attachment[] Array of Attachment Objects
discussionId number (optional) Discussion Id

Add Comment

Example Request (without attachment): Add Comment

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

Example Request (with attachment):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X POST \
-F "comment=<comment.json;type=application/json" \
-F "file=@file_to_attach;type=application/octet-stream"

    #
    # Content of the comment.json file:
    #
    {
        "text":"This text is the body of the new 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:

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



Creating a Comment with an Attachment:

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

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

Example Response:

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

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

Updates the text of a Comment. Note that only the user that created the comment is permitted to update it.

Updating a Comment:

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

Delete Comment

Example Request: Delete Comment

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

Example Response:

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

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

Deletes the Comment specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Get Comment

Example Request: Get Comment

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

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" : 48569348493469348,
    "id": 48569348493401200
}

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

Gets the Comment specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Comment Object

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

Objects

Contact Object

Example Contact Object:

{
    "id": "AAAAATYU54QAD7_fNhTnhA",
    "name": "David Davidson",
    "email": "dd@example.com"
}
id string Contact Id
name string Contact’s full name
email string Contact’s email address

Get Contact

Example Request: Get Contact

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

Example Response:

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

GET /contacts/{contactId}

Gets the specified Contact.

Access Scope READ_CONTACTS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Contact Object

List Contacts

Example Request: List Contacts

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

Example Response:

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

GET /contacts

Gets a list of the user’s Smartsheet Contacts.

Access Scope READ_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

Discussions

A Discussion is a collection of one or more Comments. A Discussion can exist on a Row or a Sheet.

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
title string Discussion title
comments Comment[] Array of Comment Objects
commentCount number The number of comments in the discussion
commentAttachments Attachment[] Array of Attachment Objects
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)
lastCommentedAt timestamp Time of most recent comment
lastCommentedUser User User Object containing name and email of the author of the most recent Comment
createdBy User User Object containing name and email of the creator of the Discussion
accessLevel string User’s permissions on the Discussion
readOnly Boolean Flag to indicate if the User can modify the Discussion

Create Discussion on Row

Example Request (without attachment): Create Discussion on Row

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

Example Request (with attachment):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-F "discussion=<discussion.json;type=application/json" \
-F "file=@datafile;type=application/octet-stream"

    #
    # Content of the discussion.json file:
    #
    {
        "title": "This is a new discussion with an attachment", 
        "comment": {
            "text":"This text is the body of the first comment"
        }
    }

Example Response:

{
    "message": "SUCCESS",
    "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 is a new discussion"
    },
    "version": 12,
    "resultCode": 0
}

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

Creates a new Discussion on a Row.


Creating a Discussion without an Attachment:

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body Discussion Object with the following attributes:
Returns Result Object containing Discussion Object for the newly created Discussion


Creating a Discussion with an Attachment:

Access Scope WRITE_SHEETS
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:See Multipart Uploads for more information on parts.
Returns Result Object containing a Discussion Object for the newly created Discussion, which contains a Comment Object for the initial discussion comment, which in turn contains an Attachment Object for the attachment that was uploaded to the comment.

Create Discussion on Sheet

Example Request (without attachment): Create Discussion on Sheet

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

Example Request (with attachment): Create Discussion on Sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-X POST \
-F "discussion=<discussion.json;type=application/json" \
-F "file=@file_to_attach;type=application/octet-stream"

    #
    # Content of the discussion.json file:
    #
    {
        "title": "This is a new discussion with an attachment", 
        "comment": {
            "text":"This text is the body of the first comment"
        }
    }

Example Response:

{
    "message": "SUCCESS",
    "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 is a new discussion"
    },
    "version": 12,
    "resultCode": 0
}

POST /sheets/{sheetId}/discussions

Creates a new Discussion on a Sheet.


Creating a Discussion without an Attachment:

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body Discussion Object with the following attributes:
Returns Result Object containing Discussion Object for the newly created Discussion


Creating a Discussion with an Attachment:

Access Scope WRITE_SHEETS
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:See Multipart Uploads for more information on parts.
Returns Result Object containing a Discussion Object for the newly created Discussion, which contains a Comment Object for the initial discussion comment, which in turn contains an Attachment Object for the attachment that was uploaded to the comment.

Delete Discussion

Example Request: Delete Discussion

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

Example Response:

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

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

Deletes the Discussion specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

List Discussions

Example Request: List Discussions

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

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"
                    },
                    "attachments": [
                        {
                            "id": 1055252897130372,
                            "name": "test.html",
                            "attachmentType": "FILE",
                            "mimeType": "text/html",
                            "sizeInKb": 13,
                            "createdBy": {
                                "name": "Test User",
                                "email": "tester@smartsheet.com"
                            },
                            "createdAt": "2015-01-12T18:23:02-08:00"
                        }
                    ],
                    "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 (both sheet-level discussions and row-level discussions).

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

Get Discussion

Example Request: Get Discussion

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

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.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Discussion Object

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"

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"
                    },
                    "attachments": [
                        {
                            "id": 1055252897130372,
                            "name": "test.html",
                            "attachmentType": "FILE",
                            "mimeType": "text/html",
                            "sizeInKb": 13,
                            "createdBy": {
                                "name": "Test User",
                                "email": "tester@smartsheet.com"
                            },
                            "createdAt": "2015-01-12T18:23:02-08:00"
                        }
                    ],
                    "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.

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

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” sheets, reports, folders, workspaces, Sight, 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
}
type string One of:
  • workspace
  • folder
  • sheet
  • report
  • template
  • Sight
objectId number Id of the favorited item. If type is “template”, only private sheet-type template Id is allowed.

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

Example Response:

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

POST /favorites

Adds one or more items to the user’s list of Favorite items.

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.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body Favorite Object or an array of Favorite Objects, with the following attributes:
  • type
  • objectId
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.

List Favorites

Example Request: List Favorites

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

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.

Access Scope READ_SHEETS
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

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

Example Response:

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

DELETE /favorites/folder/{folderId}

Removes a single Folder from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Remove Favorite Report

Example Request: Remove Favorite Report

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

Example Response:

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

DELETE /favorites/report/{reportId}

Removes a single Report from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Remove Favorite Sheet

Example Request: Remove Favorite Sheet

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

Example Response:

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

DELETE /favorites/sheet/{sheetId}

Removes a single Sheet from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Remove Favorite Sight

Example Request: Remove Favorite Sight

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

Example Response:

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

DELETE /favorites/sights/{sightId}

Removes a single Sight from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Remove Favorite Template

Example Request: Remove Favorite Template

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

Example Response:

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

DELETE /favorites/template/{templateId}

Removes a single Template from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Remove Favorite Workspace

Example Request: Remove Favorite Workspace

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

Example Response:

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

DELETE /favorites/workspace/{workspaceId}

Removes a single Workspace from the user’s list of Favorite items.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

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

Example Response:

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

DELETE /favorites/folder

Removes multiple Folders from the user’s list of Favorite items.

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

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

Example Response:

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

DELETE /favorites/report

Removes multiple Reports from the user’s list of Favorite items.

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

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

Example Response:

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

DELETE /favorites/sheet

Removes multiple Sheets from the user’s list of Favorite items.

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

Remove Multiple Favorite Sights

Example Request: Remove Multiple Favorite Sights

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

Example Response:

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

DELETE /favorites/sights

Removes multiple Sights from the user’s list of Favorite items.

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

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

Example Response:

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

DELETE /favorites/template

Removes multiple Templates from the user’s list of Favorite items.

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

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

Example Response:

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

DELETE /favorites/workspace

Removes multiple Workspaces from the user’s list of Favorite items.

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

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
name string Folder name
favorite Boolean Returned only if the user has marked the Folder as a Favorite in their Home tab (value = 'true’)
permalink string URL that represents a direct link to the Folder in Smartsheet
sheets Sheet[] Array of Sheet Objects
folders Folder[] Array of Folder Objects
reports Report[] Array of Report Objects
templates Template[] Array of Template Objects

Copy Folder

Example Request: Copy Folder

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

Example Response:

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

POST /folders/{folderId}/copy

Creates a copy of the specified Folder.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Parameters include (optional) – a comma-separated list of elements to copy:
  • data
  • attachments
  • discussions
  • cellLinks
  • forms
  • all - specify a value of “all” to include everything (data, attachments, discussions, cellLinks, and forms)
Note: Cell history is not copied, regardless of which include parameter values are specified.
skipRemap (optional) – – comma-separated list of references to NOT re-map for the newly created folder:
  • cellLinks
  • reports
  • sheetHyperlinks
  • Sights
By default, all cell links, reports, sheet hyperlinks, and Sights that reference objects in the source folder are re-mapped to reference corresponding objects in the newly created folder. The skipRemap parameter can be specified to change that default behavior:
  • If “cellLinks” is specified in the skipRemap parameter value, the cell links within the newly created folder continue to point to the original source sheets.
  • If “reports” is specified in the skipRemap parameter value, the reports within the newly created folder continue to point to the original source sheets.
  • If “sheetHyperlinks” is specified in the skipRemap parameter value, the sheet hyperlinks within the newly created folder continue to point to the original source sheets.
  • If “Sights” is specified in the skipRemap parameter value, the widgets within Sights in the newly created folder continue to point to the original source sheets / reports.
Request Body ContainerDestination Object
Returns Result Object containing a Folder Object for the newly created Folder

Create Child Folder

A Folder can be created in the user’s Sheets folder (Home), in another Folder, or in a Workspace.

Create Folder

Example Request: Create Folder

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

Example Response:

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

POST /home/folders

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

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

Create Folder (Folder)

Example Request: Create Folder (Folder)

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

Example Response:

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

POST /folders/{folderId}/folders

Creates a Folder in the specified Folder.

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

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

Example Response:

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

POST /workspaces/{workspaceId}/folders

Creates a Folder in the specified Workspace.

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

Delete Folder

Example Request: Delete Folder

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

Example Response:

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

DELETE /folders/{folderId}

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

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Get Folder

Example Request: Get Folder

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

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

GET /folders/{folderId}

Gets the specified Folder (and lists its contents).

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters include (optional) – a comma-separated list of optional elements to include in the response:
  • ownerInfo - owner’s email address and user Id for each sheet
  • source - the source for any sheet that was created from another sheet or template
Returns Folder Object, populated according to the include parameter

Note: If no folders, sheets, reports, templates, or Sights are present in the Folder, the corresponding attribute (for example, “folders”, “sheets”) is not present in the response.

Get All Child Folders

Top-level child Folders can be retrieved from the user’s Sheets folder (Home), from another Folder, or from a Workspace.

List Folders

Example Request: List Folders

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

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 7116448184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 7116448184188022,
            "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).

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

List Folders (Folder)

Example Request: List Folders (Folder)

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

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 7116448184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 7116448184188022,
            "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.

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

List Folders (Workspace)

Example Request:

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

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 7116448184199044,
            "name": "Folder 1",
            "permalink": "https://app.smartsheet.com/b/home?lx=9sljohj8jEXqvJIbTrK2Hb"
        },
        {
            "id": 7116448184188022,
            "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.

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

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

Example Response:

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

POST /folders/{folderId}/move

Moves the specified Folder to another location.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body ContainerDestination Object, limited to the following required attributes:
  • destinationType
  • destinationId
Returns Result Object containing a Folder Object for the moved Folder

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

Example Response:

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

PUT /folders/{folderId}

Updates the Folder specified in the URL.

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

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
name string Group name
description string Group description
owner string Group owner’s email address
ownerId number Group owner’s User Id
members GroupMember[] Array of GroupMember Objects
createdAt timestamp Time of creation
modifiedAt timestamp Time of last modification

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

Example Response:

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

POST /groups

Creates a new Group.

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

Delete Group

Example Request: Delete Group

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

Example Response:

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

DELETE /groups/{groupId}

Deletes the Group specified in the URL.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Get Group

Example Request: Get Group

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

Example Response:

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

GET /groups/{groupId}

Gets the Group specified in the URL.

Access Scope READ_USERS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Group Object that includes the list of GroupMembers

List Org Groups

Example Request: List Org Groups

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

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 the list of all Groups in an organization. To fetch the members of an individual group, use the Get Group operation.

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

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

Example Response:

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

PUT /groups/{groupId}

Updates the Group specified in the URL.

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

A Group is comprised of one or more members.

Members of a Group

For details about working with a Group’s members, see Group Members.

Group Members

A Group Member is a User that belongs to a Group.

Objects

Example GroupMember Object

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

GroupMember Object

id number Group Member’s User Id
email string Group Member’s email address
firstName string Group Member’s first name
lastName string Group Member’s last name
name string Group Member’s full name

Add Group Members

Example Request: Add Group Members

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

Example Response:

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

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.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body A single GroupMember Object or an array of GroupMember Objects, limited to the following attribute:
  • email
Returns Result Object containing the members added to the group – either a single GroupMember or array of GroupMember Objects, corresponding to what was specified in the request.
Errors If an error occurs because the request specified one or more alternate email addresses (that is, not the primary email address associated with the User account), the Error Object returned contains a detail attribute set to an array of objects, each object in the array has the following attributes:
  • alternateEmailAddress: User’s alternate email address that was specified in the request
  • primaryEmailAddress: User’s primary email address that must instead be specified for the operation
For example:
{
  “errorCode”: 5xxx,
  “message”: “u1+1@smartsheet.com is an alternate address of the user u1@smartsheet.com. Please retry using their primary address u1@smartsheet.com.”
  “detail”: [
      {
        “alternateEmailAddress”: “u1+1@smartsheet.com”,
        “primaryEmailAddress”: “u1@smartsheet.com”
      }
  ]
}

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

Example Response:

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

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

Removes a member from a Group.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns Result Object

Home

In the Smartsheet UI, the “Home” tab shows all objects a User has access to, including Sheets, Folders, Workspaces, Reports, and Templates.

Objects

Home Object

Example Home Object:

{
    "folders": [],
    "sheets": [],
    "reports": [],
    "templates": [],
    "workspaces": [],
    "sights": []
}
sheets Sheet[] Array of Sheet Objects
folders Folder[] Array of Folder Objects
reports Report[] Array of Report Objects
templates Template[] Array of Template Objects
workspaces Workspace[] Array of Workspace Objects
Sights Sight[] Array of Sight Objects

List Contents

Example Request: List Contents

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

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 Sheets, Workspaces, Folders, Reports, Templates, and Sights, as shown on the Home tab.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters include (optional) – a comma-separated list of optional elements to include in the response:
  • ownerInfo - owner’s email address and user Id for each sheet
  • source - the source for any sheet that was created from another sheet or template
Returns Home Object, populated according to the include parameter

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.

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/or Discussions.

Objects

Report Object

Example Report Object:

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

Extends the Sheet Object, adding the following:

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

ReportCell Object

Extends the Cell Object, adding the following:

virtualColumnId number The virtual Id of the cell’s column. This property refers to the cell’s parent column in the Report, while the columnId property refers to the cell’s parent column in its originating source Sheet.

ReportColumn Object

Extends the Column Object, adding the following:

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

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

ReportRow Object

Extends the Row Object, adding the following:

sheetId number The Id of the Sheet from which the Row originates

ReportPublish Object

readOnlyFullEnabled Boolean If true, a rich version of the report is published with the ability to download row attachments and discussions.
readOnlyFullUrl string URL for 'Read-Only Full’ view of the published report
Only returned in a response if readOnlyFullEnabled = true.
readOnlyFullAccessibleBy string Flag to indicate who can access the 'Read-Only Full’ view of the published report:
  • If “ALL”, it is available to anyone who has the link.
  • If “ORG”, it is available only to members of the report owner’s Smartsheet organization.
Only returned in a response if readOnlyFullEnabled = true.

Get Report

Example Request: Get Report

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

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,
            "index": 0,
            "primary": true,
            "title": "Sheet Name",
            "type": "TEXT_NUMBER",
            "validation": false,
            "sheetNameColumn": true
        },
        {
            "virtualId": 2331373580117892,
            "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 Discussions, Attachments, and source Sheets.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters include (optional) – a comma-separated list of optional elements to include in the response:
  • discussions
  • attachments
  • format
  • sourceSheets
exclude (optional) – a comma-separated list of optional elements to not include in the response.
  • linkInFromCellDetails: excludes the following attributes from the cell.linkInFromCell Object:
    • status
    • rowId
    • columnId
  • linksOutToCellsDetails: excludes the following attributes from the cell.linksOutToCells array elements:
    • status
    • rowId
    • columnId
pageSize (optional): Number of rows per page. If not specified, the default value is 100. This operation can return a maximum of 500 rows per page.
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

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

Example Response:

# See local file named "output.xlsx"

Example Request: Get Report as CSV

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

Example Response:

# See local file named "output.csv"

GET /reports/{reportId}

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

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

List Reports

Example Request: List Reports

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

Example Response:

{
    "pageNumber": 1,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {   
            "id": 6761305928427396,
            "name": "r1",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=zWThapjNSR8LxW_kTdxPhQ"
        },  
        {   
            "id": 4508956358928260,
            "name": "r2",
            "accessLevel": "OWNER",
            "permalink": "https://app.smartsheet.com/b/home?lx=33-Y5QkQw6ZNSoApMKntbw"
        }   
    ]   
}

GET /reports

Gets the list of all Reports that the User has access to, in alphabetical order, by name.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters modifiedSince (optional): when specified with a date and time value, response only includes the objects that are modified on or after the date and time specified.
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 Report Objects limited to the following attributes:
  • id
  • name
  • accessLevel
  • permalink

Publish Report

Get Report Publish Status

Example Request: Get Report Publish Status

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

Example Response:

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

GET /reports/{reportId}/publish

Gets the Report’s 'Publish’ settings.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Returns ReportPublish Object

Set Report Publish Status

Example Request: Set Report Publish Status

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

Example Response:

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

PUT /reports/{reportId}/publish

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

Access Scope ADMIN_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body ReportPublish Object limited to the following attributes:
  • readOnlyFullEnabled (required)
  • readOnlyFullAccessibleBy (optional) - set to either “ALL” or “ORG”, when readOnlyFullEnabled=true.
To publish the Report, set readOnlyFullEnabled to true. To unpublish the Report, set readOnlyFullEnabled to false.
Returns Result Object containing a ReportPublish Object

Send Report via Email

Example Request: Send Report

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

Example Response:

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

POST /reports/{reportId}/emails

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

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

Share Report

For details about Report sharing, see Report Sharing.

A Report is comprised of Columns, Rows, and Cells, and may optionally contain Attachments and/or Discussions.

Report Attachments

For details about working with a Report’s attachments, see Attachments.

Report Cells

For details about working with a Report’s cells, see Cells.

Report Columns

For details about working with a Report’s columns, see Columns.

Report Discussions

For details about working with a Report’s discussions, see Discussions.

Report Rows

For details about working with a Report’s rows, see Rows.

Rows

A Row is a component of a Sheet or Report. Each Row is composed of a collection of Cells, and may optionally contain Discussions and/or Attachments.

Objects

Row Object

Example Row Object:

{
    "id": 2361756178769796,
    "sheetId": 4583173393803140,
    "rowNumber": 1,
    "expanded": true,
    "cells": [],
    "createdAt": "2012-07-24T23:10:55-07:00",
    "modifiedAt": "2012-07-24T23:14:27-07:00"
}
id number Row Id
sheetId number Parent Sheet Id
rowNumber number Row number within the sheet (1-based - starts at 1)
version number Number that is incremented every time a sheet is modified
filteredOut Boolean true if this row is filtered out by a column filter (and thus is not displayed in the Smartsheet app), false if the row is not filtered out.
Only returned if the include query string parameter contains filters.
inCriticalPath Boolean Only returned, with a value of true, if the sheet is a project sheet with dependencies enabled and this row is in the critical path
locked Boolean Flag indicating whether the row is locked. In a response, a value of true indicates that the row has been locked by the sheet owner or the admin.
lockedForUser Boolean Flag indicating whether the row is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.
expanded Boolean Flag to indicate if the row is expanded or collapsed
accessLevel string User’s permission level on the Sheet that contains the Row
format string Format descriptor (see Formatting).
Only returned if the include query string parameter contains format and this row has a non-default format applied.
conditionalFormat string Format descriptor describing this row’s conditional format (see Formatting)
Only returned if the include query string parameter contains format and this row has a conditional format applied.
createdAt timestamp Time of creation
createdBy User User Object containing name and email of the creator of this row
modifiedAt timestamp Time of last modification
modifiedBy User User Object containing name and email of the last person to modify this row
cells Cell[] Array of Cell Objects belonging to the row
discussions Discussion[] Array of Discussion Objects.
Only returned if the include query string parameter contains discussions.
attachments Attachment[] Array of Attachment Objects.
Only returned if the include query string parameter contains attachments.
columns Column[] Array of Column Objects.
Only returned if the Get Row include query string parameter contains columns.
permalink string URL that represents a direct link to the Row in Smartsheet
Only returned if the include query string parameter contains rowPermalink.
parentId number In a response - the Id of the parent row (if any).

In a request - the Id of the desired parent row (used to specify the location for a new or moved row). For more information, see Row Location.
siblingId number In a response - the Id of the previous sibling row at the same hierarchical level of this row (if any).

In a request - the Id of the desired sibling row (used to specify the location for a new or moved row). For more information, see Row Location.
toTop Boolean Flag used to specify the location for a new or moved row. This attribute can be specified in a request, but is never present in a response. For more information, see Row Location.
toBottom Boolean Flag used to specify the location for a new or moved row. This attribute can be specified in a request, but is never present in a response. For more information, see Row Location.
above Boolean Flag used to specify the location for a new or moved row. This attribute can be specified in a request, but is never present in a response. For more information, see Row Location.

CopyOrMoveRowDirective Object

rowIds number[] The Ids of the rows to move or copy from the source sheet
to CopyOrMoveRowDestination A CopyOrMoveRowDestination Object that identifies the destination sheet

CopyOrMoveRowDestination Object

sheetId number Id of the destination sheet

CopyOrMoveRowResult Object

destinationSheetId number Id of the destination sheet
rowMappings RowMapping[] Array of RowMapping Objects

RowMapping Object

from number Row Id in the source sheet
to number Row Id in the destination sheet

Add Rows

Example Request: Add Rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"toTop":true, "cells": [ {"columnId": 7960873114331012, "value": true}, {"columnId": 642523719853956, "value": "New status", "strict": false} ] }, {"toTop":true, "cells": [ {"columnId": 7960873114331012, "value": true}, {"columnId": 642523719853956, "value": "New status", "strict": false} ] }]'

Example Response:

{
    "message": "SUCCESS",
    "result": [
        {
            "id": 7670198317672324,
            "sheetId": 2331373580117892,
            "rowNumber": 1,
            "expanded": true,
            "createdAt": "2013-02-28T17:45:13-08:00",
            "modifiedAt": "2013-02-28T17:45:13-08:00",
            "cells": [
                {
                    "columnId": 7960873114331012,
                    "type": "CHECKBOX",
                    "value": true
                },
                {
                    "columnId": 642523719853956,
                    "displayValue": "New status",
                    "type": "TEXT_NUMBER",
                    "value": "New status"
                }
            ]
        },
        {
            "id": 2040698783459204,
            "sheetId": 2331373580117892,
            "rowNumber": 2,
            "expanded": true,
            "createdAt": "2013-02-28T17:45:13-08:00",
            "modifiedAt": "2013-02-28T17:45:13-08:00",
            "cells": [
                {
                    "columnId": 7960873114331012,
                    "type": "CHECKBOX",
                    "value": true
                },
                {
                    "columnId": 642523719853956,
                    "displayValue": "New status",
                    "type": "TEXT_NUMBER",
                    "value": "New status"
                }
            ]
        }
    ],
    "version": 14, 
    "resultCode": 0
}

POST /sheets/{sheetId}/rows

Inserts one or more rows into the Sheet specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Parameters allowPartialSuccess (optional): when specified with a value of true, enables partial success for this bulk operation. See Partial Success for more information.
overrideValidation (optional): You may use the query string parameter overrideValidation with a value of true to allow a cell value outside of the validation limits. You must specify strict with a value of false to bypass value type checking.
Request Body Row object or an array of Row objects, with the following attributes:

  • One or more location-specifier attributes (optional)
  • expanded (optional)
  • format (optional)
  • cells (optional) – if specified, must be an array of Cell objects, where each object is limited to the following attributes:
    • columnId (required)
    • One of the following (required):
      • value
      • formula
    • When value is specified
      • strict (optional)
      • hyperlink (optional) with exactly one of the following attributes set:
        • url
        • sheetId
        • reportId
      • linkInFromCell (optional) with all of the following attributes set:
        • sheetId
        • rowId
        • columnId
    • overrideValidation (optional)
    • format (optional)
  • locked (optional) - true to lock the row or false to unlock the row.
See Column Types for more information.

Please note the following:
  • Column Ids must be valid for the sheet to which the row belongs, and must only be used once for each row in the operation.
  • Cells of a project sheet in the “Finish Date” column cannot be updated via API.
  • Cells of a project sheet in the “Start Date” column cannot be updated via API for rows that contain a value in the “Predecessor” column.
  • Max length for a cell value is 4000 characters after which truncation occurs without warning. Empty string values are converted to null.
  • Calculation errors or problems with a formula will not cause the API call to return an error code. Instead, the response will contain the same value as in the UI, such as cell.value = “#CIRCULAR REFERENCE”.

Returns Result object containing the newly created rows – either a single Row object or array of Row objects, corresponding to what was specified in the request, as well as the new version of the Sheet.
Errors When allowPartialSuccess=false (or not specified):

If an error occurs, the Error object returned contains a detail attribute set to an object with the following attribute:
  • index: the array index of the row that caused the error (0 if a single Row was passed in)
If any error occurs, the entire request fails (no rows are added), and the Error response returned describes the first problem that was encountered. For example:
{
  “errorCode”: 1042,
  “message”: “The cell value in column 5504245941200772 did not conform to the strict requirements for type CHECKBOX.”
  “detail”: {
    “index”: 4
  }
}


When allowPartialSuccess=true:

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

Copy Rows to Another Sheet

Example Request: Copy Rows to Another Sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/copy \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "rowIds": [145417762563972, 8026717110462340], "to": {"sheetId": 2258256056870788} }'

Example Response:

{
    "destinationSheetId": 2258256056870788,
    "rowMappings": [
        {    
            "from": 145417762563972,
            "to": 4508365800925060
        },   
        {    
            "from": 8026717110462340,
            "to": 2256565987239812
        }    
    ]    
}

POST /sheets/{sheetId}/rows/copy

Copies Rows from the Sheet specified in the URL to (the bottom of) another sheet.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Parameters include (optional) – comma-separated list of row elements to copy in addition to the cell data:
  • attachments
  • discussions
  • children - if specified, any child rows of the rows specified in the request are also copied to the destination sheet, and parent-child relationships amongst rows are preserved within the destination sheet; if not specified, only the rows specified in the request are copied.
  • all - specify a value of “all” to include everything (attachments, discussions, and children)
ignoreRowsNotFound (optional) – true or false: default is false. If set to true, specifying row Ids that do not exist within the source sheet does not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet causes an error response (and no rows are copied).
Request Body CopyOrMoveRowDirective Object
Returns CopyOrMoveRowResult Object

Delete Rows

Example Request: Delete Rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows?ids={rowId1},{rowId2},{rowId3}&ignoreRowsNotFound=true \
-X DELETE

Example Response:

{
    "resultCode": 0,
    "result": [
        145417762563972,
        4508365800925060,
        8026717110462340,
        2256565987239812 
    ],
    "message": "SUCCESS"
}

DELETE /sheets/{sheetId}/rows?ids={rowId1},{rowId2},{rowId3}

Deletes one or more rows from the Sheet specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters ids (required) - comma-separated list of Row Ids
ignoreRowsNotFound (optional) - true or false. If set to false and any of the specified Row Ids are not found, no rows are deleted, and the “not found” error is returned.
Returns Result Object containing Row Ids corresponding to all rows that were successfully deleted (including any child rows of rows specified in the URL).

Get Row

Example Request: Get Row

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

Example Response:

{
    "id": 2361756178769796,
    "sheetId": 4583173393803140,
    "rowNumber": 1,
    "expanded": true,
    "cells": [
        {
            "columnType": "TEXT_NUMBER",
            "value": "Revision 1",
            "displayValue": "Revision 1",
            "columnId": 4583173393803140
        },
        {
            "columnType": "PICKLIST",
            "value": "completed",
            "displayValue": "completed",
            "columnId": 2331373580117892
        }
    ],
    "createdAt": "2012-07-24T23:10:55-07:00",
    "modifiedAt": "2012-07-24T23:14:27-07:00"
}

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

Gets the Row specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters include (optional) – a comma-separated list of elements to include in the response.

See Row Include Flags.
Also supports the columns include flag, which adds a columns array that specifies all of the columns for the sheet. This enables you to have the full context of the cells in the row.

The filters include flag may be used in conjunction with columns to include the user’s column filters with the columns.
exclude (optional) – a comma-separated list of elements to not include in the response.
  • nonexistentCells: excludes cells that have never contained any data
  • linkInFromCellDetails: excludes the following attributes from the cell.linkInFromCell Object:
    • status
    • rowId
    • columnId
  • linksOutToCellsDetails: excludes the following attributes from the cell.linksOutToCells array elements:
    • status
    • rowId
    • columnId
Returns Row Object, populated according to the specified parameters

List Rows

To get the list of all Rows in a Sheet, use the Get Sheet operation.

Move Rows to Another Sheet

Example Request: Move Rows to Another Sheet

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/move \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "rowIds": [145417762563972, 8026717110462340], "to": {"sheetId": 2258256056870788} }'

Example Response:

{
    "destinationSheetId": 2258256056870788,
    "rowMappings": [
        {    
            "from": 145417762563972,
            "to": 4508365800925060
        },   
        {    
            "from": 8026717110462340,
            "to": 2256565987239812
        }    
    ]    
}

POST /sheets/{sheetId}/rows/move

Moves Rows from the Sheet specified in the URL to (the bottom of) another sheet.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Parameters include (optional) – comma-separated list of row elements to move in addition to the cell data:
  • attachments
  • discussions
ignoreRowsNotFound (optional) – true or false: default is false. If set to true, specifying row Ids that do not exist within the source sheet do not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet causes an error response (and no rows are moved).
Request Body CopyOrMoveRowDirective Object
Returns CopyOrMoveRowResult Object

Send Rows via Email

Example Request: Send Rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient@smartsheet.com"} \
    ], \
    "subject": "some subject", \
    "message": "some message", \
    "ccMe": false, \
    "rowIds": [ \
        rId1, \
        rId2 \
    ], \
    "columnIds": [ \
        cId1, \
        cId2 \
    ], \
    "includeAttachments": false, \
    "includeDiscussions": false \
}'

Example Response:

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

POST /sheets/{sheetId}/rows/emails

Sends one or more Rows via email.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body MultiRowEmail Object.

The columns included for each row in the email are populated according to the following rules:
  • If the columnIds attribute of the MultiRowEmail Object is specified as an array of column Ids, those specific columns are included.
  • If the columnIds attribute of the MultiRowEmail Object is omitted, all columns except hidden columns shall be included.
  • If the columnIds attribute of the MultiRowEmail Object is specified as empty, no columns shall be included. (Note: In this case, either includeAttachments:true or includeDiscussions:true must be specified.)
Returns Result Object

Send Update Request

Example Request: Create Update Request

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient1@smartsheet.com"}, \
        {"email": "recipient2@smartsheet.com"} \
    ], \
    "subject": "Sample Monthly Update Request", \
    "message": "Please update my online sheet.", \
    "ccMe": false, \
    "rowIds": [4508292249610116, 2256492435924868], \
    "columnIds": [4508284196546436, 2256484382861188], \
    "includeAttachments": false, \
    "includeDiscussions": false \
}'

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "sendTo": [
            {"email": "recipient1@smartsheet.com"},
            {"email": "recipient2@smartsheet.com"}
        ],
        "subject": "some subject",
        "message": "some message",
        "ccMe": false,
        "includeAttachments": false,
        "includeDiscussions": false,
        "columnIds": [4508284196546436, 2256484382861188],
        "rowIds": [4508292249610116, 2256492435924868],
        "id": 4523799765903236,
        "sentBy": {
            "name": "John Doe",
            "email": "john.doe@smartsheet.com"
        },
        "schedule": {
            "type": "ONCE",
            "startAt": "2016-05-16T22:33:28Z",
            "nextSendAt": "2016-05-16T22:33:28Z"
        }
    }
}

Example Request: Create Immediate Update Request

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient1@smartsheet.com"} \
    ], \
    "subject": "Sample Monthly Update Request", \
    "message": "Please update my online sheet.", \
    "ccMe": false, \
    "rowIds": [7886095586224004], \
    "columnIds": [6962516556310404, 3584816835782532], \
    "includeAttachments": true, \
    "includeDiscussions": true, \
    "schedule": { \
        "type": "MONTHLY", \
        "startAt": "2016-04-01T19:00:00Z", \
        "endAt": "2016-12-31T07:00:00Z", \
        "dayOfMonth": 1, \
        "repeatEvery": 1 \
    } \
}'

Example Response:

{
    "message": "SUCCESS",
    "resultCode": 0,
    "result": {
        "sendTo": [
            {"email": "recipient1@smartsheet.com"}
        ],
        "subject": "Sample Monthly Update Request",
        "message": "Please update my online sheet.",
        "ccMe": false,
        "includeAttachments": true,
        "includeDiscussions": true,
        "columnIds": [6962516556310404, 3584816835782532],
        "rowIds": [7886095586224004],
        "id": 7820135625975684,
        "sentBy": {
            "name": "John Doe",
            "email": "john.doe@smartsheet.com"
        },
        "schedule": {
            "type": "MONTHLY",
            "startAt": "2016-04-01T19:00:00Z",
            "endAt": "2016-12-31T07:00:00Z",
            "dayOfMonth": 1,
            "repeatEvery": 1,
            "nextSendAt": "2016-05-01T19:00:00Z"
        }
    }
}

POST /sheets/{sheetId}/updaterequests

Creates an Update Request for the specified Row(s) within the Sheet. An email notification (containing a link to the update request) will be sent to the specified recipient(s) according to the specified scheduled.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body UpdateRequest Object.

The UpdateRequest Object in the request body must specify one or more of the following attributes:
  • sendTo: Recipient[]
  • rowIds: number[]
  • One or more of the followings:
    • columnIds: number[]
    • includeAttachments: true
    • includeDiscussions: true
The following attributes have the following values when not specified:
  • Subject: Update Request: {Sheet Name}
  • Message: Please update the following rows in my online sheet.
  • ccMe: false
When the Schedule Object is not specified, the request is sent to the recipients immediately.
Returns Result Object containing the newly created UpdateRequest Object.
Errors If an error occurs because the request specified one or more alternate email addresses (that is, not the primary email address associated with the User account), the Error Object returned contains a detail attribute set to an array of objects, each object in the array having the following attributes:
  • alternateEmailAddress: User’s alternate email address that was specified in the request
  • primaryEmailAddress: User’s primary email address that must instead be specified for the operation
For example:
{
  “errorCode”: 5xxx,
  “message”: “u1+1@smartsheet.com is an alternate address of the user u1@smartsheet.com. Please retry sharing directly to u1@smartsheet.com.”
  “detail”: [
      {
        “alternateEmailAddress”: “u1+1@smartsheet.com”,
        “primaryEmailAddress”: “u1@smartsheet.com”
      }
  ]
}

Update Rows

Example Request: Update Rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X PUT \
-d '[{"id": "6572427401553796", "cells": [{"columnId": 7518312134403972,"value": "new value"}, {"columnId": 1888812600190852,"value": "A"}]}, {"id": "2068827774183300", "cells": [{"columnId": 7518312134403972,"value": "desc_updated"}, {"columnId": 1888812600190852,"value": "B"}]}]'

Example Response:

{
    "message": "SUCCESS",
    "result": [
        {
            "id": 2068827774183300,
            "rowNumber": 2,
            "parentRowNumber": 1,
            "parentId": 4624744004773764,
            "expanded": true,
            "createdAt": "2015-01-09T11:41:55-08:00",
            "modifiedAt": "2015-02-23T15:36:07-08:00",
            "cells": [
                {
                    "columnId": 7518312134403972,
                    "type": "TEXT_NUMBER",
                    "value": "desc_updated",
                    "displayValue": "desc_updated"
                },
                {
                    "columnId": 1888812600190852,
                    "type": "PICKLIST",
                    "value": "B",
                    "displayValue": "B"
                },
                {
                    "columnId": 6392412227561348,
                    "type": "TEXT_NUMBER",
                    "value": 1,
                    "displayValue": "1"
                }
            ]
        },
        {
            "id": 6572427401553796,
            "rowNumber": 3,
            "parentRowNumber": 1,
            "parentId": 4624744004773764,
            "expanded": true,
            "createdAt": "2015-01-09T11:41:55-08:00",
            "modifiedAt": "2015-02-23T15:36:07-08:00",
            "cells": [
                {
                    "columnId": 7518312134403972,
                    "type": "TEXT_NUMBER",
                    "value": "new value",
                    "displayValue": "new value"
                },
                {
                    "columnId": 1888812600190852,
                    "type": "PICKLIST",
                    "value": "A",
                    "displayValue": "A"
                },
                {
                    "columnId": 6392412227561348,
                    "type": "TEXT_NUMBER",
                    "value": 1,
                    "displayValue": "1"
                }
            ]
        }
    ],
    "version": 8,
    "resultCode": 0
}

PUT /sheets/{sheetId}/rows

Updates cell values in the specified rows, expands/collapses the specified rows, and/or modifies the position of specified rows (including indenting/outdenting).

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Parameters allowPartialSuccess (optional): when specified with a value of true, enables partial success for this bulk operation. See Partial Success for more information.
overrideValidation (optional): You may use the query string parameter overrideValidation with a value of true to allow a cell value outside of the validation limits. You must specify strict with a value of false to bypass value type checking.
Request Body Row object or an array of Row objects, with the following attributes:
  • id (required)
  • One or more location-specifier attributes (optional)
  • expanded (optional)
  • format (optional)
  • cells (optional) – if specified, must be an array of Cell objects, where each object is limited to the following attributes:
    • columnId (required)
    • One of the following (required):
      • value
      • formula
    • When value is specified
      • strict (optional)
      • hyperlink (optional) with exactly one of the following attributes set:
        • url
        • sheetId
        • reportId
      • linkInFromCell (optional) with all of the following attributes set:
        • sheetId
        • rowId
        • columnId
    • overrideValidation (optional)
    • format (optional)
  • locked (optional) - true to lock the row or false to unlock the row.
See Column Types for more information.

Please note the following:
  • Column Ids must be valid for the sheet to which the row belongs, and must only be used once for each row in the operation.
  • Cells of a project sheet in the “Finish Date” column cannot be updated via API.
  • Cells of a project sheet in the “Start Date” column cannot be updated via API for rows that contain a value in the “Predecessor” column.
  • Max length for a cell value is 4000 characters after which truncation occurs without warning. Empty string values are converted to null.
  • Calculation errors or problems with a formula will not cause the API call to return an error code. Instead, the response will contain the same value as in the UI, such as cell.value = “#CIRCULAR REFERENCE”.

Returns Result object containing an array of the updated rows.
Errors When allowPartialSuccess=false (or not specified):

If an error occurs, the Error Object returned contains a detail attribute set to an object with the following attributes:
  • index: the array index of the row that caused the error (0 if a single Row was passed in)
  • rowId: the id of the row that caused the error (omitted if the row was missing an id)
If any error occurs, the entire request fails (no rows are updated), and the Error response returned describes the first problem that was encountered. For example:
{
  “errorCode”: 1042,
  “message”: “The cell value in column 5504245941200772 did not conform to the strict requirements for type CHECKBOX.”
  “detail”: {
    “index”: 4
    “rowId”: 6572427401553796
  }
}


When allowPartialSuccess=true:

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

A Row is comprised of a collection of Cells, and may optionally contain Attachments and/or Discussions.

Row Attachments

For details about working with a Row’s attachments, see Attachments.

Row Cells

For details about working with a Row’s cells, see Cells.

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

Row Discussions

For details about working with a Row’s discussions, see Discussions.

Row Include Flags

Endpoints which return rows (for example, get sheet, get row) support the optional include query string parameter. If specified, the value of the include parameter is a comma-delimited list of flags that indicate additional attributes to be included in each Row Object within the response.

Include Flag Notes
discussions Includes row discussions array.
To include discussion attachments, both attachments and discussions must be present in the include list.
attachments Includes row attachments array.
To include discussion attachments, both attachments and discussions must be present in the include list.
format Includes format attribute on the row and its cells. See Formatting.
filters Includes filteredOut attribute indicating if the row should be displayed or hidden according to the sheet’s filters.
columnType Includes columnType attribute in the row’s cells indicating the type of the column the cell resides in.
rowPermalink Includes permalink attribute that represents a direct link to the row in the Smartsheet application.
rowWriterInfo Includes createdBy and modifiedBy attributes on the row, indicating the row’s creator, and last modifier.
objectValue Includes objectValue attribute on cells containing values. For more information see Cell Reference.

Row Location

When using the Add Rows operation to insert new rows into a sheet or the Update Rows to move rows in a sheet, the following “location-specifier” Row attributes can be used to specify where the rows get added or moved to in the sheet:

  • toTop
  • toBottom
  • above
  • siblingId
  • parentId
  • indent (applicable when updating a row only)
  • outdent (applicable when updating a row only)

The following table describes which location-specifier Row attributes should be set to implement various actions.

Action Row attributes
Add or move the Row to the top of the Sheet. toTop = true
Add or move the Row to the bottom of the Sheet. toBottom = true
Add or move the Row directly above the specified sibling Row (at the same hierarchical level). above = true
siblingId = (Id of sibling row)
Add or move the Row directly below the specified sibling Row (at the same hierarchical level). siblingId = (Id of sibling row)
Add or move the Row so that it is the first child row of the specified parent Row. parentId = (Id of parent row)
Add or move the Row so that it is the last child row of the specified parent Row. parentId = (Id of parent row)
toBottom = true
Indent an existing Row. indent = (number of level to indent, minimum of 1)
Outdent an existing Row. outdent = (number of level to outdent, minimum of 1)

Search

Use the Search operations to search a specific Sheet or to search across all Sheets that a User can access.

Objects

SearchResult Object

Example SearchResult Object:

{
    "results": [
        {
            "contextData": [
                "Discussion 1"
        ],
        "objectId": 1888207043356548,
        "objectType": "discussion",
        "parentObjectId": 7141187195824004,
        "parentObjectName": "Sheet 1",
        "parentObjectType": "sheet",
        "text": "discussion stuff goes here"
        }
    ],
    "totalCount": 2
}
totalCount number Total number of search results
results SearchResultItem[] Array of SearchResultItem Objects

SearchResultItem Object

text string Search result text excerpt
objectId number Search result object Id
objectType string Search result object type (row, sheet, report, template, discussion, attachment)
parentObjectId number Search result parent object Id
parentObjectType string Search result parent object type (workspace, folder, sheet, report, template)
parentObjectName string Search result parent object name
contextData array Additional info on search result context (row num)

Search Everything

Example Request: Search Everything

curl https://api.smartsheet.com/2.0/search?query=stuff \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

Example Response:

{
    "results": [
        {
            "contextData": [
                "Discussion 1"
            ],
            "objectId": 1888207043356548,
            "objectType": "discussion",
            "parentObjectId": 7141187195824004,
            "parentObjectName": "Sheet 1",
            "parentObjectType": "sheet",
            "text": "discussion stuff goes here"
        },
        {
            "contextData": [
                "Row 1"
            ],
            "objectId": 2711817823774596,
            "objectType": "row",
            "parentObjectId": 2583735121012612,
            "parentObjectName": "Sheet 2",
            "parentObjectType": "sheet",
            "text": "row stuff goes here"
        }
    ],
    "totalCount": 2
}

GET /search

Searches all Sheets that the User can access, for the specified text.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters query (required): Text with which to perform the search.
Returns SearchResult Object that contains a maximum of 100 SearchResultems

Search Sheet

Example Request: Search Sheet

curl https://api.smartsheet.com/2.0/search/sheets/{sheetId}?query=stuff \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"

Example Response:

{
    "results": [
        {
            "contextData": [
                "Discussion 1"
            ],
            "objectId": 1888207043356548,
            "objectType": "discussion",
            "parentObjectId": 7141187195824004,
            "parentObjectName": "Sheet 1",
            "parentObjectType": "sheet",
            "text": "discussion stuff goes here"
        }
    ],
    "totalCount": 1
}

GET /search/sheets/{sheetId}

Searches a Sheet for the specified text.

Access Scope READ_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Parameters query (required): Text with which to perform the search. Use double-quotes for an exact search.
Returns SearchResult Object that contains a maximum of 100 SearchResultems

Send via Email

Use the Send operations to send a Report, a Row, or a Sheet via email.

Objects

Example Email Object

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

Email Object

sendTo Recipient[] Array of Recipient Objects. Required.
subject string The subject of the email. Optional.
message string The message of the email. Optional.
ccMe Boolean A flag to indicate whether or not to send a copy of the email to the sender. Optional, defaults to false.

FormatDetails Object

paperSize string One of the following values: LETTER, LEGAL, WIDE, ARCHD, A4, A3, A2, A1, A0.

Recipient Object

Specifies the recipient of an Email. The recipient may be either an individual or a group. To specify an individual, set the email attribute; to specify a group, set the groupId attribute. Either email and groupId may be set, but not both.

email string The email address of an individual recipient. Optional.
groupId number The Id of a group recipient. Optional.

RowEmail Object

Extends the Email Object, adding the following:

columnIds number[] Ids of the columns to be included.
includeAttachments Boolean A flag to indicate whether or not to include Attachments in the email.
includeDiscussions Boolean A flag to indicate whether or not to include Discussions in the email.
layout string One of the following values: HORIZONTAL, VERTICAL. Optional, defaults to HORIZONTAL when multiple rows are being sent, and to VERTICAL when a single row is being sent. HORIZONTAL formats the rows being sent as a grid, whereas VERTICAL formats the rows being sent as separate cards.

MultiRowEmail Object

Extends the RowEmail Object, adding the following:

rowIds number[] Ids of rows to be included.

SheetEmail Object

Extends the Email Object, adding the following:

format string One of the following values:
  • PDF
  • PDF_GANTT
  • EXCEL
formatDetails FormatDetails A FormatDetails Object.

Send Report

Example Request: Send Report

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

Example Response:

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

POST /reports/{reportId}/emails

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

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

Send Rows

Example Request: Send Rows

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient@smartsheet.com"} \
    ], \
    "subject": "some subject", \
    "message": "some message", \
    "ccMe": false, \
    "rowIds": [ \
        rId1, \
        rId2 \
    ], \
    "columnIds": [ \
        cId1, \
        cId2 \
    ], \
    "includeAttachments": false, \
    "includeDiscussions": false \
}'

Example Response:

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

POST /sheets/{sheetId}/rows/emails

Sends one or more Rows via email.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Type: application/json
Request Body MultiRowEmail Object.

The columns included for each row in the email are populated according to the following rules:
  • If the columnIds attribute of the MultiRowEmail Object is specified as an array of column Ids, those specific columns are included.
  • If the columnIds attribute of the MultiRowEmail Object is omitted, all columns except hidden columns shall be included.
  • If the columnIds attribute of the MultiRowEmail Object is specified as empty, no columns shall be included. (Note: In this case, either includeAttachments:true or includeDiscussions:true must be specified.)
Returns Result Object

Send Sheet

Example Request: Send Sheet

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

Example Response:

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

POST /sheets/{sheetId}/emails

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

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

Send Update Request

Example Request: Create Update Request

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient1@smartsheet.com"}, \
        {"email": "recipient2@smartsheet.com"} \
    ], \
    "subject": "Sample Monthly Update Request", \
    "message": "Please update my online sheet.", \
    "ccMe": false, \
    "rowIds": [4508292249610116, 2256492435924868], \
    "columnIds": [4508284196546436, 2256484382861188], \
    "includeAttachments": false, \
    "includeDiscussions": false \
}'