Smartsheet

Updated 2024-04-22

Introduction

Smartsheet API 2.0 allows you to programmatically access and manage your organization's Smartsheet data and account information. The API is restricted to users on a Business or Enterprise plan. The API allows you to do the following:

• Read or update sheets
• Manage folders and workspaces
• Administer user accounts and organization account

Once you scroll to the Developer Reference section, you can view code examples in the programming language of your choice by clicking the corresponding tab in the rightmost pane. Each tab corresponds to a Software Development Kit (SDK) that Smartsheet provides to make working in that programming language easier. See SDKs and Sample Code.

NOTES:

• For the introduction, the rightmost pane is blank. Code samples are visible there at the endpoint level.
• If you have feedback on the documentation, you can reach us using the Smartsheet Community API Category.
• Your use of the Smartsheet APIs and SDKs are governed by the Developer Agreement.

API Basics

Assume User

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

An admin cannot impersonate another admin.

NOTE: You must manually generate a token to assume user.

cURL example

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

C# example

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

Java example

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

Node.js example

// Set options
var options = {
assumeUser: "jane.doe@smartsheet.com"
};
// List Sheets
smartsheet.sheets.listSheets(options)
.then(function(sheetList) {
console.log(sheetList);
})
.catch(function(error) {
console.log(error);
});

Python example

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

Ruby example

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

Authentication and Access Tokens

When choosing an authentication method, it’s important to consider your integration scenario. Do you want user consent and interaction or is your integration machine-to-machine?

When user consent and interaction are involved, we recommend OAuth 2.0 as a best practice. Note that the Smartsheet implementation of OAuth 2.0 is a 3-legged process, which requires human intervention. See the OAuth process for a code walkthrough.

When creating machine-to-machine integrations, making a raw token request is recommended. Raw API tokens provide a straightforward, yet secure, method of authentication without the need for human intervention.

In either scenario, an HTTP header containing an access token is required to authenticate each request.

WARNING: If an unauthorized user gets a copy of this token, they will be able to access all Smartsheet data that you have access to, both to read and modify on your behalf. You should keep your tokens secure and do not share them with anyone. See Security for best practices.

Dates and Times

The Smartsheet API returns all dates and times in the UTC time zone in ISO-8601 format, that is, YYYY-MM-DDTHH:MM:SSZ. If you are specifying a date and time, you should also send that information in ISO-8601 format. If a date/time needs to be displayed to an end-user in their local time zone, you must do the conversion using the user's time zone, which you can obtain by getting the current user.

You can optionally choose to receive and send dates/times in numeric format, as milliseconds since the UNIX epoch (midnight on January 1, 1970 in UTC time), using the query string parameter numericDates with a value of true. This query parameter works for any API request.

NOTE: Some SDK methods use language-specific Date objects, which require different date formats.

Filtering

You cannot create or update filters using the API; however, you can query which rows have been filtered out and you can get filter definitions.

For details, see Filters object.

Formatting

To set or read formatting programmatically, Smartsheet uses a compact format string, cell.format, which looks something like this: ",,1,1,,,,,,,,,,,,,". The position and sample values in this string are explained in the following format descriptor table:

Format Descriptor Table

NOTES:

• Formats that have not been explicitly set are omitted in the descriptor string. For example, a cell that has been set to bold and italic, but has no other formats applied to it, has a format descriptor of ",,1,1,,,,,,,,,,,,,".
• Use GET /serverinfo to return the FormatTables object, which tells you both the default settings and what formatting options are available.

Applying Formatting

Use the "include=format" query-string parameter on API operations that return detailed objects, such as GET /sheets/{sheetId} or GET sheets/{sheetId}/rows/{rowId}. If there is formatting other than default settings, the return includes a format property. If an object has conditional formatting, the format property returned will have a conditionalFormat value.

Setting the format of a row object or column object through the API simply sets the baseline format for new or blank cells in that row or column. It does not affect cells that already have a value.

If you want to change the formatting of cells that already have content, for instance you want to make a row bold, then you have to set the format for each cell individually.

Formulas

Formulas are processed per cell in the UI. Use the Cell object to manipulate formulas via the API.

For requests, use Update Rows to add or update the formula in a cell.

For response payloads, formulas (when present) are returned whenever the Cell object is returned, so for example, GET /sheets/(id) returns the Cell object for each cell and that object contains a formula value when the cell contains a formula.

HTTP and REST

The REST URL structure follows typical resource-oriented conventions.

To get a list of sheets, use the following:

GET https://api.smartsheet.com/2.0/sheets

This returns a list of Sheet objects, where each sheet has an id attribute.

To get details on the sheet with id 123456, use the following:

GET https://api.smartsheet.com/2.0/sheets/123456

This Id pattern is repeated throughout the API. Columns, rows, cells, comments, attachments, or any other data element have a unique Id.

If you don't want to make raw HTTP calls, Smartsheet also has several Software Development Kits (SDKs) that provide a higher level interface for popular programming languages. For more information, see SDKs and Sample Code.

HTTP 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:

HTTP Verbs

Call the API using the following standard HTTP methods:

• GET (to retrieve an object or list 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.

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.

NOTE: Smartsheet has custom error codes to help you troubleshoot issues. See the complete Error Code List.

Limitations

While Smartsheet is improving capacity frequently, there are some hard limits that might be helpful to know:

• When adding or updating rows, limit your request to 500 rows at a time.
• A sheet cannot exceed a total of 500,000 cells. To determine how close you are to the 500,000 cell limit, multiply the number of columns in your sheet by the number of rows. For example, a sheet with 20,000 rows can only have 25 or fewer columns, and a sheet with 400 columns can only have 1,250 or fewer rows.
• Any one sheet can have up to 500,000 inbound cell links. (Smartsheet Gov has an inbound cell link limit of 100,000.)
• No cell can contain more than 4,000 characters.
• When using a GET /reports/{reportId} call with paging, the default is 100 rows. If you need larger sets of data from your report, this operation can return a maximum of 10,000 rows per request.
• Reports are limited to 50,000 rows.
• When sharing emails, you can send 1000 per API call.

The following features aren't yet supported for sheets with more than 5000 rows, or more than 200 columns:

• Bridge by Smartsheet
• Quip connector
• Tableau connector
• PowerBI connector
• Zapier connector
• Google Docs Merge connector
• Google Forms sync connector
• LiveData connector
• Calendar App

Looping

Looping is an expected action when working with the Smartsheet API. But when do you run the For Loop? Do you loop through multiple endpoint calls or is there a more efficient way?

For instance, if you're looking for multiple values on a given sheet, fetch the entire sheet. Do the searching on the return data in one single For Loop rather than calling the search endpoint multiple times with different values.

Multi-contact or Multi-picklist: Working with Complex Objects

New column types, such as MULTI_CONTACT_LIST and MULTI_PICKLIST, offer more complex ways to work with columns. Smartsheet has provided a backwards compatible way for these payloads to work with your existing integrations while also giving you a way to query for their content.

With either column type, there are two ways of receiving the response:

• If you do nothing to your code, column types will display as TEXT_NUMBER
• If you use the level query parameter as detailed below, column types will display as MULTI_CONTACT_LIST or MULTI_PICKLIST and return a complex object (aka a non-primitive type)

Smartsheet uses two indicators to help you discover changes in the return data for your API calls:

• level: a query parameter that is incremented when a new feature or column type is added
• version: each element in the Columns array is set to one of the following values:

You must use the level query parameter, for example level=2, to return a complex object with the new column type. Without the query parameter, the response will be backwards-compatible, that is a string. The include=objectValue query parameter is necessary to see the return as a complex value, such as actual email addresses rather than display names.

Use the highest possible level for each endpoint, as in the following table:

Object Details vs List Summaries

Many of the List All commands, for example, GET /sheets, return only an abbreviated object for each object returned. For full details, read a single item, such as GET /sheets/{sheetId}. In many cases, you can refine the exact object properties to be returned by using include and exclude query parameters.

The JSON representation of the objects returned from the List All REST endpoints will only include a subset of the properties documented here. However, the objects returned from the Java and C# SDKs will represent the omitted properties with NULLs.

Query Strings

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

NOTE: Query strings are case sensitive. If you do not see the expected response, confirm that your query is formatted correctly.

Raw Token Requests

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

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

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

Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

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

NOTE: A best practice is to use a shared account, such as ticket-processor@example.com, rather than your individual work account.

SDKs and Sample Code

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

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

The SDKs ease use of the Smartsheet APIs. Benefits include:

• Retry with backoff to automatically recover from network errors or rate limiting
• Request & response logging
• Native object models for request and responses (Java and C# only)

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

*The Ruby SDK is no longer maintained. It is still usable, but new functionality may be missing.

Sheets/Columns/Rows/Cells

Sheets have a core hierarchy of Sheet > Column > Row > Cell. The strict hierarchy tells you how to associate the objectId with the object. For example, your return might include a Sheet object with many Row objects. Each object has an objectId. The strict hierarchy helps you map the objectId to the sheet or specific row.

Cells are a little different. You identify a cell by its location in the grid, so you need both a column Id and a row Id to pinpoint a specific cell. The following table defines these terms and points you to places in this documentation where you can find more information:

Versioning and Changes

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

When there is new functionality that is not compatible with existing code, say in the case of a new concept, Smartsheet increments the level to indicate the new feature can be ignored until you are ready to implement the code to work with the new level.

See also: Multi-contact or Multi-picklist: Working with Complex Objects

Code Walkthrough

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, "JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789", with your actual token value.

WARNING: If an unauthorized user gets a copy of this token, they will be able to access all Smartsheet data that you have access to, both to read and modify on your behalf. You should keep your tokens secure and do not share them with anyone. See Security for best practices.

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

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

In Postman, the request looks like this:

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

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

How to Read a Sheet Response

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

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

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

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

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

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

{
"id": 6141831453927300, // Sheet Id
"name": "My first sheet",
"columns": [{ // Each Column object associates column Id
// to title and defines the
// column details
"id": 2517104256673668, // Column Id
"index": 0,
"title": "Name",
"type": "TEXT_NUMBER",
"primary": true,
"width": 150
},
{
"id": 7020703884044164, // Next column Id
"index": 1,
"title": "EmployeeId",
"type": "TEXT_NUMBER",
"width": 150
}
],
"rows": [{ // A Row object
"id": 564480076736388, // Row Id
"rowNumber": 1,
"expanded": true,
"createdAt": "2017-05-12T16:52:38Z",
"modifiedAt": "2017-05-22T20:40:14Z",
"cells": [{ // Each row contains an array of cells,
// which have the actual content
"columnId": 2517104256673668,
// The column Id can be interpreted by
// looking at the array of column
// definitions above. That tells you
// this is the "Name" column
"value": "John Doe",
"displayValue": "John Doe"
},
{
"columnId": 7020703884044164,
"value": 12345, // Actual cell value
"displayValue": "12,345"
// How the cell value is displayed in the UI
}
]},
{
"id": 5068079704106884,
"rowNumber": 2,
"siblingId": 564480076736388,
"expanded": true,
"createdAt": "2017-05-12T16:52:38Z",
"modifiedAt": "2017-05-22T20:40:14Z",
"cells": [{
"columnId": 2517104256673668,
"value": "Jane Roe",
"displayValue": "Jane Roe"
},
{
"columnId": 7020703884044164,
"value": 67890,
"displayValue": "67890"
}
]
}
]
}

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

Error Code List

For an explanation of the logic behind Smartsheet error codes and error handling, see the HTTP and REST portion of the Introduction.

400-Level Error Codes

400-level error codes generally indicate that there is something you should fix or add to your request before you try the request again.

500-Level Error Codes

500-level error codes indicate there is some kind of permanent error.

OAuth Walkthrough

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

NOTE: For users of apps like AWS AppFabric, you will need a Tenant ID. You can find your Tenant ID in Admin Center under Security & Controls. There is a Smartsheet Tenant ID pane.

First Steps

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

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

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

NOTE: Your use of the Smartsheet APIs and SDKs are governed by the Developer Agreement.

Open Developer Tools

1. Log in to Smartsheet with your developer account.
2. Click the "Account" button in the lower-left corner of your Smartsheet screen, and then click "Developer Tools".
3. Do one of the following:

• If you need to register an app, click "Create New App".
• If you need to manage an app, click "view/edit" for the app.

Register Your App Using Developer Tools

1. Log in to Smartsheet with your developer account.
2. Click the "Account" button in the upper-right corner of your Smartsheet screen, and then click "Developer Tools".
3. In the "Create New App" form, provide the following information:

• Name: the name the user sees to identify your app
• Description: a brief description intended for the user
• URL: the URL to launch your app, or the landing page if not a web app
• Contact/support: support information for the user
• Redirect URL: also known as a callback URL. The URL within your application that will receive the OAuth 2.0 credentials After you click "Save", Smartsheet assigns a client Id and secret to your app. Make a note of these Ids for the next steps; however, you can always look them up again in "Developer Tools".

OAuth Flow

Your app must implement a 3-legged OAuth flow to retrieve an access token it can use to access Smartsheet data on behalf of an end user. The following diagram has an overview of the OAuth flow:

NOTE: App registration and OAuth flow require HTTPS.

Access Scopes

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

The access scopes are as follows:

NOTE: Additional Info:

• When you request an authorization code, you specify all of the access scopes you need for your app. Smartsheet encodes those permissions into the auth code and subsequent access token.
• Your app must request at least one access scope, but should only request the scopes necessary.
• Once your app attains a valid access token, it can execute a Get Current User operation, regardless of which access scopes were requested.

Request an Authorization Code

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

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

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

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

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

NOTE: If the user has not yet logged into Smartsheet, the redirect will first take them to a login page, and then display the consent page.

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

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

If the User Clicks Allow

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

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

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

If the User Clicks Deny

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

Get or Refresh an Access Token

Once you’ve successfully obtained an authorization code, the next step is to exchange the code for an access token. (Remember, the authorization code expires after 599135 milliseconds.)

Access tokens expire after 604799 seconds, which is approx 7 days. Use the refresh token to obtain a new access token and a new refresh token. Once you obtain the new tokens, you must use them in place of the old ones, which are no longer valid.

To get or refresh an access token, see Refresh Access Token.

OAuth Error Types

Resources

Please note the following resources:

• Smartsheet Developer Portal: If registering, you must use an email address with a Smartsheet account; however, you may want to use a service or test account so you can test the API and make API calls
• Smartsheet Community
• Contact us--regular commercial accounts
• Contact us for Smartsheet Regions-Europe
• Resource Management API documentation
• StackOverflow using the "smartsheet-api" tag

NOTE: Your use of the Smartsheet APIs and SDKs are governed by the Developer Agreement.

Security

The following provides some best practices to consider when working with the Smartsheet API and any API keys, tokens, or other sensitive information.

Adding Security by Using OAuth

If your application requires users to be able to login with their own account, you must implement the full OAuth flow.

At a high level, this involves the following steps:

1. Register as a Developer with Smartsheet so you can get access to the Developer Tools menu.
2. Register your app to get both a clientId and client secret, which you'll need to store securely. Some best practices suggestions for security are below.
3. Go through the steps in the OAuth Walkthrough once you are ready to request authorization.

NOTE: When using OAuth, be sure to review the Access Scopes needed for your app and only request the necessary scopes.

Access Levels

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

The accessLevel attribute has one of the following values:

NOTE: Smartsheet also uses access scopes. Access levels describe the actual permissions a specific user has for a specific sheet or other resource. Access scopes describe the general categories of access requested by a third-party app.

API Key Management

If you've committed code to a repository before implementing these security best practices, here are some steps to resecure your API keys.

For raw tokens:

1. Revoke token
2. Create a new token

If using OAuth for an integration:

• Work through the OAuth Walkthrough to regenerate client secrets, auth codes, and tokens.

Source Code and Version control

Never commit API keys to accessible version control systems like GitHub or BitBucket. Instead, you should:

• Use an app configuration tool suitable for deploying secrets to your app, or
• Use a config file outside of source control, or
• Use environment variables set outside of source control.

If you have mistakenly deployed API keys to a publicly accessible location such as GitHub, then you should immediately revoke those API keys, revise your application to use a preferred method of key deployment, and then generate new keys.

If you need to store API keys in a database, consider the following protections:

• Restrict access so API keys are only readable by the owner of the object
• Restrict read privileges to the database table
• Make sure your database or the disk the database is on is set to encrypt data at rest

NOTE: When using any Smartsheet SDK, you can use the environment variable of SMARTSHEET_ACCESS_TOKEN. If the access token is null on input to the client builder, the SDK will automatically pick up the value of that environment variable.

Smartsheet Gov

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

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

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

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

Smartsheet Regions Europe

Smartsheet Regions Europe is a separate data island. As an API developer working on a Smartsheet Regions Europe account, you should be aware of the following differences from the standard API:

• The base URL for each API call is smartsheet.eu instead of smartsheet.com. This documentation uses smartsheet.com in all examples.
• Smartsheet Regions Europe aka Smartsheet EU uses a separate token from Smartsheet.com.

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

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

Troubleshooting

Should you encounter issues with the Smartsheet API while building an integration using a particular programming language, for example C#, Java, Node.js, Python, or Ruby, keep the following troubleshooting techniques in mind.

Try executing the same API Request using a tool like cURL or Postman. By taking your code out of the equation, you can isolate troubleshooting to the raw Request / Response.

• If you receive a similar error when you execute the Request using cURL or Postman, this suggests an issue with the Request format or contents. Once you have the Request working in cURL or Postman, update your code accordingly.
• If you can execute the Request successfully using cURL or Postman, but not via your code, this suggests that the Request your code is sending is somehow different than what you intend. Compare the (successful) Request from cURL or Postman with the (unsuccessful) Request that your code generates. (See step #2 below.)

Examine the Request that your code is sending (including the HTTP verb, URI, headers, and Request body) and the Response that it's receiving back from Smartsheet (including the HTTP status code, headers, and response body).

• If you've implemented Request / Response logging in your application, inspect the full trace of Request and Response in the log file. Compare the Request that your application is logging with the (successful) Request from cURL or Postman, and update your code to correct any discrepancies.
• Alternatively, you may choose to use a tool like Fiddler or Charles HTTP Proxy to inspect the full trace of Request and Response as it goes across the wire. Compare the Request trace that your application generates with the (successful) Request from cURL or Postman, and update your code to correct any discrepancies.

Check for capitalization errors. NOTE: URL endpoints are all lower case, while object properties and query parameters are camelCase.

Work at Scale

Bulk Operations

The Smartsheet API supports a number of bulk operations that can operate on multiple objects. Unlike single-object operations, bulk operations allow you to create, update, or delete multiple objects in a single request. For example, if you want to update 10 rows within a sheet, do so using a single Update Rows request, rather than executing 10 separate requests - one for each row.

Optional Bulk Operations

Several endpoints support optional bulk POST operations which exist alongside the standard single-object POST. For these endpoints, you may pass in either a single object or an array of objects. Depending on what was passed in, the Result object returned contains either a single object or an array. An example optional bulk operation is POST /favorites: you can pass in a single Favorite object to create a single favorite, or an array of Favorite objects to create multiple favorites in a single request. Endpoints which support bulk operations are noted as such in the API reference documentation.

NOTE: Most POST operations fail when attempting to create a single object which already exists (for example, favorites, shares, group members). However, for the corresponding bulk operations, these endpoints do not return an error if one or more items in the array already exist. Existing items are simply ignored, and the Result object returned omits them.

Partial Success

In general, the default behavior for bulk operations is to fail outright if any of the objects in the request are invalid for some reason. If successful, Smartsheet creates/updates/deletes all objects in the request; if not, no objects are changed.

However, there are some operations that support partial success, which means the operation still succeeds even if one or more of the objects in the request fails for some reason (for example, an object is invalid). Here is another example: if you want to update more than one row, you send more than one row object in your request. If a row object is invalid, that row update will fail, but the other row updates will succeed. Partial success is not the default mode for an operation and you must explicitly enable it by using a query string parameter. This is noted in the documentation for operations that support partial success.

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

Paging

The Smartsheet API contains a number of index endpoints (typically denoted in the documentation with titles beginning with "Get All" or "List") which return arrays of objects. Examples include GET /users, /sheets, /sheets/{sheetId}/columns, and many others. These endpoints all support pagination, meaning you can retrieve paged subsets of results, enabling you to process potentially large result sets in smaller chunks.

Paging Query String Parameters

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

NOTE: Most index endpoints default to a page size of 100 results. If you want all results at once, you must specify the includeAll=true query string parameter.

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:

Rate Limiting

Handle "Rate limit exceeded" Error

To prevent abuse and undue stress on the Smartsheet servers, Smartsheet reserves the right to enforce some limits depending on the load on our systems. This reduction is sometimes called rate limiting or throttling. Certain operations, such as attaching a file and getting cell history, are resource intensive.

The Smartsheet API implements "rate limiting" to protect the system. When API calls exceed an acceptable load, an HTTP 429 status will be returned along with the following 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 a minimum of 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). Note that the SDKs implement this behavior.

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

NOTE: Attempts to perform multiple concurrent updates to a sheet may result in error code 4004.

Use the Smartsheet SDKs

The SDKs provide default backoff and retry to accommodate rate limiting responses from the API. Note that the default maximum retry duration is typically 30 seconds. You may wish to increase this if your application is making many API calls in quick succession. For specific instructions per language, see the Readme for the respective SDK.

Authentication

Operations