We are delighted to announce public availability of Smartsheet API 2.0!  This new version of the API contains both new operations and some fairly significant changes to several existing operations.  Whether you are just getting started with the Smartsheet API or already have experience using API 1.1, this post contains important information for you.

Since its initial launch in 2013, the Smartsheet API, we’ve been working hard to consistently expand API capabilities.  For some time now, we’ve done so by making non-breaking, backward-compatible changes to version 1.1 of the API.  Due to the nature and scope of changes this time around, we’ve elected to release a brand new version of the API which is significantly different from API 1.1 in many ways and introduces breaking, non-backward-compatible changes.

So, what’s so great about API 2.0?  Valuable features like multipart upload, bulk-insert / bulk-update, and pagination of results enable greater efficiency when it comes to how you interact with your Smartsheet data.  Redesign of some existing operations mean a much simpler implementation and a greatly improved developer experience.  Availability of new endpoints allow you to interact with Smartsheet data in ways that were previously not possible.  We’re pretty fond of API 2.0, and think you will be too.

If you’re new to using the Smartsheet API, you’ll want to use API 2.0 from the start.  Head on over to the Smartsheet API 2.0 documentation for comprehensive information about the Smartsheet API, and check out the Smartsheet Developer Portal for additional resources to help you along the way.

If you’re an existing Smartsheet developer who’s previously built integrations using version 1.1 of the API, read on to learn about key changes introduced by this release.  The information below will help you to plan and implement your migration from version 1.1 to version 2.0 of the API.

 

 


 

Changes to HTTP header requirements

This API release changes the way that HTTP headers are processed.  The following requirements apply to both API 1.1 and API 2.0, effective immediately.  Whether you're using API 1.1 or API 2.0, you should ensure that the HTTP headers specified in your requests comply with the following requirements.

HTTP Header

Old behavior

New requirement

Accept

Previously, parsing of the "Accept" HTTP header was very lenient.

 


If you specified an Accept header and it simply started with one of our supported MIME types (e.g. "application/json"), we would use that value for processing the request.  

 


If you specified no Accept header, or specified an invalid or unrecognized header value, we would default to JSON.

Accept header parsing has been updated to be more in-line with the HTTP specification, including support for complex values and quality parameters.

As a result, the API (v1.1 and v2.0) does not support invalid and unrecognized Accept header values, and will return error code 1052 ("Invalid Accept header. Media type not supported.") in response to such values. 

 


We recommend setting the Accept header for all requests.  Most API operations expect a value of "application/json".

Content-Type

Previously, parsing of the "Content-Type" HTTP header was very lenient.

 


If you specified no Content-Type header, or specified an invalid or unrecognized header value, we would default to JSON.

The API (v1.1 and v2.0) requires a Content-Type HTTP header for PUT and POST operations.

 


For most regular API operations, the value of the Content-Type header should be set to "application/json".  Upload operations (e.g. create attachment) expect a Content-Type header value of either "multipart/form-data", or the MIME type of the file uploaded, depending on which upload mechanism you use.

 

 

 




Smartsheet API 1.1 Deprecation

With this release of API 2.0, version 1.1 of the Smartsheet API has been officially deprecated.  What does this mean for you as a Smartsheet developer?  

First and foremost, it means that any new development from now on should use Smartsheet API 2.0.  If you’re building a new integration from scratch, you’ll find everything you need to know in our Smartsheet API 2.0 documentation.  

It also means that any existing integrations will need to be updated from version 1.1 to version 2.0 of the Smartsheet API.  Smartsheet API 1.1 will continue to be supported until July 31, 2016, at which time it will no longer be supported and may stop functioning without any notice.  We encourage you to migrate to version 2.0 as soon as possible, so that you can begin taking advantage of the new features and functionality, and avoid any potential disruptions when API 1.1 is decommissioned in July 2016.

 

 


Migrating from API 1.1 to API 2.0

Since API 2.0 evolved from API 1.1, it’s naturally similar to version 1.1 in many ways.  However, there are some significant differences.  No matter what type of integration you’ve built using API 1.1, some degree of code changes will be required to migrate the integration from API 1.1 to API 2.0.  

The information below is intended as an overview of changes in API 2.0, to help you plan and implement your migration from API 1.1 to API 2.0.  For comprehensive information about API 2.0, see the API 2.0 documentation.

 


Main Categories of Changes

At a high level, changes in API 2.0 can be categorized as follows:

  • New base URL - https://api.smartsheet.com/2.0
  • New endpoints - new operations for Columns, Reports, Rows, Templates, and Access Tokens
  • Changed endpoints - several changes to existing endpoints, including:
    • Changed numerous endpoints from singular to plural - For example:
      • v1.1:  GET /sheet/{sheetId}/columns
      • v2.0:  GET /sheets/{sheetId}/columns
    • Changed endpoints for all Sharing-related operations
    • Changed endpoint for Update Row(s) operation
  • New support for multipart upload requests
  • New support for pagination of results
  • New support for bulk-insert & bulk-update
  • Other miscellaneous changes  

See below for more detailed information about each category of change.

 

 


New Base URL

The base URL for all Smartsheet API 2.0 requests is:  

  • https://api.smartsheet.com/2.0

New Endpoints

The following new endpoints have been added in API 2.0.  

Operation

HTTP Method

Endpoint

Get Column

GET

/sheets/{sheetId}/columns/(columnId}

Get Report as Excel / CSV

GET

/reports/{reportId}

List Reports

GET

/reports

Copy Row(s) to Another Sheet

POST

/sheets/{sheetId}/rows/copy

Move Row(s) to Another Sheet

POST

/sheets/{sheetId}/rows/move

List Public Templates

GET

/templates/public

Revoke Access Token

DELETE

/token

 

 



Changed Endpoints

 

 

Changed endpoints from singular to plural

Nearly 80 endpoints have been changed in API 2.0 to use the plural form of the associated resource.  For example:

  • v1.1 endpoint for Get All Columns:  GET /sheet/{sheetId}/columns
  • v2.0 endpoint for Get All Columns:  GET /sheets/{sheetId}/columns

For a complete list of endpoints that have changed from singular to plural, see API 2.0 Changed Endpoints - Singular to Plural.  

 

 


Changed endpoints for all Sharing-related operations

Endpoints for all Sharing-related operations have changed in API 2.0.  Rather than use the shareswithgroups path as API 1.1 does, API 2.0 uses the simpler shares path.  For a complete list of Sharing-related endpoints that have changed in API 2.0, see API 2.0 Changed Endpoints - Sharing.  

 

 


Changed endpoint for Update Row(s) operation

API 2.0 adds the capability to update multiple rows using a single request (i.e., bulk-update).  To facilitate this enhancement, the endpoint for Update Row(s) operation has changed to:

  • PUT /sheets/{sheetId}/rows

For details about this operation, see the Update Row(s) section in the Smartsheet API 2.0 documentation.

 

 


New support for multipart upload requests

API 2.0 adds support for multipart upload requests to several operations.  A multipart upload request allows you to add a single file attachment to the specified object (i.e., 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.   For more information, see the Multipart Uploads section in the Smartsheet API 2.0 documentation.  For a complete list of operations that support multipart upload requests in API 2.0, see API 2.0 - Support for Multipart Uploads.

 


New support for pagination of results

API 2.0 adds support for pagination of results to several operations.  The ability to retrieve paged subsets of results enables you to process potentially large result sets in smaller chunks.  For a complete list of operations that support pagination of results in API 2.0, see API 2.0 - Support for Pagination of Results.  Each operation that supports pagination of results in API 2.0 now returns the actual results encapsulated in an IndexResult object within the response.  For more information, see the Paging section in the Smartsheet API 2.0 documentation.

 

 


New support for bulk-insert and bulk-update

API 2.0 adds support for bulk-insert and bulk-update to several operations, enabling you to create or update multiple items using a single request.  For a list of operations that support bulk-insert and bulk-update in API 2.0, see API 2.0 - Support for Bulk-insert and Bulk-update.  For more information, see the Bulk-insert Operations section in the Smartsheet API 2.0 documentation.  (Note: Although only a handful of operations are enabled for bulk-insert and bulk-update in the initial release of API 2.0, we’ll likely be enabling this functionality for additional operations in the future.)

 


Other miscellaneous changes

In addition to the major categories of changes described above, API 2.0 introduces numerous other miscellaneous changes, including:

  • Date/Time values returned in UTC

  • New column types

  • New error codes

  • Updated objects

  • Updated operations

The sections below describe many of these changes.  For comprehensive details, see the Smartsheet API 2.0 documentation.

 


Date/Time values returned in UTC

API 2.0 returns all date/time values in UTC format.  For more information, see the Dates and Times section of the Smartsheet API 2.0 documentation.

 


New column types

New column types have been added (valid for dependency-enabled project sheets only):  

  • Duration

  • Predecessor

  • Date/Time

 


New error codes

Several new error codes have been added for new error scenarios. For the full list of Error Codes in API 2.0, see the Errors section in the Smartsheet API 2.0 documentation. In addition to the net-new error codes, the HTTP status code that is returned for error 4003: Rate limit exceeded has changed. API 2.0 returns HTTP status code 429 for this error (instead of the status code 503 that was returned by API 1.1).

 


Updated objects

Several objects have been updated in API 2.0:

Object

Change(s)

Cell object

Changed attribute name:  type is now columnType

 

Removed attribute:  link

Column object

New values for type attribute: DURATION, PREDECESSOR, ABSTRACT_DATETIME

Comment object

Changed attribute name: modifiedDate is now modifiedAt

Email object

The to attribute and toGroups attribute have been replaced by the sendTo attribute

 

(This change affects the Request format in the following operations:  Send Report, Send Row, Send Sheet.)

Row object

Several new attributes

 

Removed attribute:  parentRowNumber

Share object

Several new attributes

 

Note: All sharing operations have been significantly redesigned in API 2.0. Not only does each sharing-related operation in API 2.0 have a new endpoint, but the contents of Request and Response in the API 2.0 operations differs from 1.1 as well.  See the Sharing section of the Smartsheet API 2.0 Documentation for more information.

Sheet object

Several new attributes

User object

Changed attribute name:  resourceManager is now resourceViewer


 

Updated operations

Earlier sections of this post specify numerous operations that have been updated in API 2.0 to support the following features:

  • Multipart upload requests

  • Pagination of results

  • Bulk-insert & bulk-update

For details about operation updates related to any of these new features, please refer to the corresponding section earlier in this post.

 

Additionally, the following operations have also been updated in API 2.0:

Operation(s)

Change(s)

Get Folder

List Folders

List All Contents

Get Workspace

List Workspaces

These operations now return Reports and Templates by default (“reports and “templates are no longer specified as values of the include parameter)

Send Report via Email

Send Row via Email

Send Sheet via Email

Object within the request body for each of these operations now includes the sendTo attribute instead of the to attribute and the toGroups attribute

Add Row(s)

Request body now contains Row object(s) instead of RowWrapper object

Get Cell History

Get Row

Get Sheet

Within the response for each of these operations, the Cell attribute type has been changed to columnType.  

 

Additionally, this attribute is no longer returned by default for each Cell object in the response.  To receive the columnType attribute in the response, the request must specify the include parameter with a value of “columnType” (ex: ?include=columnType).

Get Row

Get Sheet

New parameter: exclude

 

Note: By default, these operations now return all cells in each Row (even those cells that have never held data). The exclude parameter can be specified to exclude cells from the response that have never held data (this was the default behavior in API 1.1).

Update Row

New attribute of Row object in Request body: locked

Sharing operations

(Reports, Sheets, Workspaces)

Significant changes to both Request and Response for all Sharing-related operations.  For details, see the Sharing section in the Smartsheet API 2.0 documentation.

Update Sheet

Now supports setting the userSettings attribute of the Sheet object in the request body

Remove User

Updated parameter: transferTo

New parameter: transferSheets

Create Workspace

New values for the include parameter: brand, shares

 

 

 




Next steps

Want to build a new integration with the Smartsheet API?  Consult the Smartsheet API 2.0 documentation for comprehensive information about our API, and check out the Smartsheet Developer Portal for additional resources to help you along the way.

 

Have an existing integration that was built using API 1.1?  Don’t forget that support for Smartsheet API 1.1 only runs through July 31, 2016, at which time it will no longer be supported and may stop functioning without any notice.  We encourage you to migrate your integration to version 2.0 as soon as possible, so that you can begin taking advantage of the new features and functionality, and avoid any potential disruptions when API 1.1 is decommissioned in July 2016.

 

We are here to support you and we want to hear from you.  If you have feedback about API 2.0, have ideas about new features, or run into an issue, drop us a line at api@smartsheet.com.

 


- The Smartsheet Platform Team

 

Categories

Comments

Hi Nao -- Thank you for your interest in our new API! Here are two resources that can help you get started -- Here is our Smartsheet Developer Portal (https://www.smartsheet.com/developers) and our Smartsheet API documentation (http://smartsheet-platform.github.io/api-docs/#smartsheet-api-2.0). Please let me know if you have any other questions! Best, Emily

I can see the zapier integration is able to get a notification when a new row is added somewhere. But I can find nothing in the API docs about getting notifications on various things, such as new row, changed dates etc.

Hi Dennis -- Zapier is able to tell when a row is added by pinging Smartsheet. Essentially, a "Get Sheet" call is being made to check various info on the specified Sheet. Zapier by itself doesn't receive notifications from Smartsheet, they are submitting API requests to Smartsheet to check the status of a specified Sheet. There is no way (yet) to receive notifications via API on when a Sheet is modified, or a Row is added. You would need to follow the same process as Zapier and run a Get Sheet operation which will return the Sheet object (which will contain a version, total row count, and an array of rows/column IDs). Smartsheet does not automatically perform this operation, it is something our partners initiate. Thanks, Emily

Hi Team, We have updated the changes from our end so I would like to know can we start testing it with the new endpoints now. As we need to test it before its go live on July 31. So please advise us on this.

Hello Sathish, You should be good to test it. If you have any questions, please feel free to contact api@smartsheet.com and we will assist you. Thanks! - The Smartsheet Team

Add new comment