Smartsheet API 2.0

Sample Code (more information here)

# The cURL code samples included in this API documentation demonstrate how to execute operations using the command line data transfer tool cURL: http://en.wikipedia.org/wiki/CURL. 
// The Node.js code samples included in this API documentation demonstrate how to execute operations using the Smartsheet JavaScript SDK: https://github.com/smartsheet-platform/smartsheet-javascript-sdk.
// The C# code samples included in this API documentation demonstrate how to execute operations using the Smartsheet C# SDK: https://github.com/smartsheet-platform/smartsheet-csharp-sdk.
// The Java code samples included in this API documentation demonstrate how to execute operations using the Smartsheet Java SDK: https://github.com/smartsheet-platform/smartsheet-java-sdk.
# The Python code samples included in this API documentation demonstrate how to execute operations using the Smartsheet Python SDK:
https://github.com/smartsheet-platform/smartsheet-python-sdk.

Overview

Introduction

Base URL: https://api.smartsheet.com/2.0

The Smartsheet API provides programmatic access to Smartsheet features and data. In designing the API, our goal was to make it simple, intuitive, and predictable. We do our best to adhere to common open and widely accepted standards, including REST for access, JSON format for the data, and OAuth for Authentication and Authorization. This API assumes a good working knowledge of the Smartsheet application UI, concepts and terminology.

RESTful Architecture

Resources:

/contacts
/favorites
/folders
/groups
/home
/reports
/search
/serverinfo
/sheets
/sheets/{id}/rows
/sheets/{id}/columns
/sheets/{id}/attachments
/sheets/{id}/discussions
/sheets/{id}/updaterequests
/templates
/token
/users
/users/{id}/alternateemails
/workspaces

Everything in Smartsheet is represented as an object with a defined structure. For example, the “Home” object contains a list of your Sheets, Folders, Reports, Templates, and Workspaces, and a Sheet object contains Columns, Rows, Attachments, and Discussions. All aspects of Smartsheet are modeled as structured objects.

URL structure follows typical resource-oriented conventions. For example, to get a list of sheets, use GET https://api.smartsheet.com/2.0/sheets. This will return a list of Sheet objects, where each Sheet will have an “id” attribute. To get details on a particular sheet, use GET https://api.smartsheet.com/2.0/sheets/123456, where 123456 is the “id” of the Sheet you want. Similarly, to share a sheet, POST a Share object to https://api.smartsheet.com/2.0/sheets/123456/shares.

HTTP Standards

All actions taken through the API are done via HTTP using standard HTTP methods: GET (to retrieve an object), POST (to create), PUT (to modify), and DELETE. Standard HTTP Response codes are used to indicate success and error conditions.

Input / Output Format

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:

Content-Type For POST and PUT requests, must be set to the appropriate value (typically application/json). Ignored for GET and DELETE requests.
Accept Optional; if not specified, */* is assumed (i.e. any response type is accepted), else it must match the output of the invoked endpoint (typically application/json).

Example Requests & Responses

For every API operation in this documentation, we show example requests in multiple languages and an example (JSON) response. You’ll see the examples displayed in the dark blue panel next to each operation. To view the sample code in a specific language, select the corresponding language tab along the top of the dark blue panel. For more information about using the sample code in this API documentation, see SDKs and Sample Code.

As with any REST API, you can also test API requests / responses using a Chrome extension like Advanced REST Client or POSTMAN.

Versioning and Changes

Non-breaking changes: We will be adding new functionality and bug fixes to the API over time. You should expect to see new endpoints or new attributes for existing objects. Such changes will not result in a new API version. Please make sure that your code can handle new attributes gracefully. Also, please make sure your code does not depend on the order in which records are returned, unless it is explicitly stated in this documentation. Finally, please be aware that a request which results in an Error response today (because the requested action is prohibited in Smartsheet) may succeed in the future, if Smartsheet functionality changes such that the previously prohibited action becomes allowed.

Breaking changes: We intend to maintain the current API version for the foreseeable future. If and when we decide to add functionality that breaks the contract of the current API, we will publish it with a new version number, so as to keep the existing API functionality backwards compatible.

Deprecations: Smartsheet occasionally deprecates APIs to indicate that those APIs should no longer be used in active development. Deprecated APIs typically remain present and usable for a reasonable period of time following the release in which they were deprecated, but may be removed entirely from a future version of the API. You should never use deprecated APIs in new development, and if you have existing code that uses deprecated APIs, we recommend that you update that code as soon as possible. For a list of Smartsheet API 2.0 deprecations, see Deprecations.

API Fundamentals

API Best Practices

We strongly recommend that you design your integration with the following guidelines in mind:

  • Be efficient: Use “bulk”-enabled operations
  • Be practical: Adhere to rate limiting guidelines
  • Be smart: Handle errors appropriately
  • Be diligent: Implement logging


Be efficient: Use “bulk”-enabled operations

For maximum efficiency, we recommend that you use bulk-enabled API operations whenever possible. A bulk-enabled API operation allows you to add, update, or delete multiple items using a single API request. For example, if you need to update 10 rows within a sheet, do so using a single Update Row(s) request, rather than executing 10 separate requests - one for each row.

Bulk-enabled operations improve efficiency by:

  • Dramatically reducing the number of outbound calls you have to make
  • Reducing your chances of hitting the rate limit (since each bulk operation counts as only one request toward the limit)
  • Lightening the load on our systems, making your requests more likely to complete in a timely manner

See the section on Bulk Operations for more details, including a list of bulk-enabled operations.


Be practical: Adhere to rate limiting guidelines

Handle “Rate Limit Exceeded” error
In order to prevent abuse and undue stress on the Smartsheet servers, the API has a rate limiting feature 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 to prevent abuse of these operations. We reserve 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 will be rejected with an 429 HTTP status code, along with the following JSON response body:

{
    "errorCode": 4003,
    "message": "Rate limit exceeded."
}

We recommend 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 Row(s) 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-enabled operation (for example, Update Row(s) or Add Column(s)).

Execute requests serially
Executing multiple API requests in parallel to update a specific Smartsheet object will result in reduced performance and will often result 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 (i.e., execute one request at time, not beginning the next request until the previous request has completed).


Be smart: Handle errors appropriately

A successful error handling strategy requires that your integration recognize the difference between errors that can potentially be resolved by retrying the request and errors that should never be retried automatically. The HTTP status code that is returned with each response is your first indication as to the outcome of the request. Message content is returned as raw text. You may need to escape it if displayed in HTML.

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.

Examples:
  • 400 Bad Request
  • 401 Not Authorized
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not Supported
  • 406 Not Acceptable
  • 415 Unsupported Media Type
  • 429 Too Many Requests
Never automatically retry the request.

If the error code indicates a problem that can be fixed, fix the problem and then retry the request.

See Error Handling for error handling recommendations by error code.
5xx The request was properly formatted, but the operation failed on Smartsheet’s end.

Examples:
  • 500 Internal Server Error
  • 503 Service Unavailable
In some scenarios, requests should be automatically retried using exponential backoff.

In other cases, requests should not be retried.

See Error Handling for error handling recommendations by error code.



In addition to the HTTP status code, you should also evaluate the Smartsheet-specific error code that’s returned in the response body for any unsuccessful request. All errors will also be accompanied by JSON-formatted error objects, containing a Smartsheet-specific error code and a descriptive message. For example, doing a GET on a non-existent sheet at https://api.smartsheet.com/2.0/sheets/123456 will result in an HTTP status code of 404, indicating the resource was not found. The body of the response will include an Error object:

{
    “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 will be noted in the specific API operation for which the error may occur.

See Error Handling for detailed error handling recommendations.


Be diligent: Implement logging

We strongly recommend that you design your integration such that it is capable of logging API requests and responses. Having access to the raw requests and responses (including detailed error codes and error messages) when API issues emerge will streamline troubleshooting and accelerate time to resolution.

The following examples show the type of information that your application should log for API requests and responses.

Request: verb, URI, header(s), request body

POST https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
Authorization: Bearer MY_TOKEN
Content-Type: application/json
[
  {
    "title": "FIRST COLUMN - My New Column",
    "index": 0,
    "type": "TEXT_NUMBER"
  },
  {
    "title": "FIRST COLUMN - My New Column",
    "index": 1,
    "type": "TEXT_NUMBER"
  }
]

Response: HTTP status code, response body

HTTP status: 400 Bad Request
{
  "errorCode": 1133,
  "message": "Column titles are not unique among input columns.",
  "detail": { "columnTitle": "FIRST COLUMN - My New Column" }
}

API Troubleshooting

Should you encounter issues with the Smartsheet API while building an integration using a particular programming language (ex: Java, C#, PHP, Python, etc.), keep the following troubleshooting techniques in mind.

  1. 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. Consult the API Documentation to ensure that the Request being sent matches what the documentation specifies. Once you have the Request working in cURL or Postman, update your code accordingly.

    • If you’re able to 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. You’ll need to compare the (successful) Request from cURL or Postman with the (unsuccessful) Request that your code is generating. (See step #2 below.)


  2. 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 (as suggested in API Best Practices), 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.

Testing with cURL

cURL is a command-line utility that you can use to execute HTTP requests. It works on a variety of platforms (PC, Mac, etc.) and provides a quick and easy way to test REST API calls. To get started with cURL, go here. Once you’ve installed cURL, you can use the cURL code samples in this API documentation (found within the cURL tab of the code samples panel) to test any Smartsheet API operation.

Testing with Postman

Postman is a browser-based REST API client that you can use with Google Chrome to execute HTTP requests. It provides a much friendlier UI than cURL and also allows you to save configuration settings and REST API requests, making it quick and easy to resume testing at any time (without having to create everything from scratch each time). To get started with Postman, go here. Test any Smartsheet API request by using this API documentation to determine the HTTP verb, URI, Headers, and Request Body that the operation requires, and plugging that information into Postman to test the request.

Authentication

The Smartsheet API utilizes OAuth 2.0 for Authentication and Authorization. An Authorization HTTP header containing an Access Token is required to authenticate requests. Access Tokens can be acquired in one of two ways:

User-generated Access Tokens

Smartsheet users can easily generate Access Tokens by logging in to their Smartsheet account. Once a token is generated, it can be used in a script or custom application, or with an API integration service like Zapier, to access any Smartsheet data which the token owner already can access in the application. See Direct API Access for more information on user-generated tokens.

Third-party Access Tokens

Third-party developers are able to build applications that can acquire Access Tokens using OAuth 2.0. See Third Party App Development for more information.

Access Levels

Throughout the API we have “Share” objects that represent the shared user’s access level. Also, on Sheets, Workspaces and Templates, there is 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:

VIEWER The user has read-only access to the resource.
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.
ADMIN The user can edit and share the resource, and can alter the structure of the resource as well.
OWNER The user has complete control over the resource.

Rate Limiting

Handle “Rate Limit Exceeded” error
In order to prevent abuse and undue stress on the Smartsheet servers, the API has a rate limiting feature 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 to prevent abuse of these operations. We reserve 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 will be rejected with an 429 HTTP status code, along with the following JSON response body:

{
    "errorCode": 4003,
    "message": "Rate limit exceeded."
}

We recommend 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 Row(s) 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-enabled operation (for example, Update Row(s) or Add Column(s)).

Execute requests serially
Executing multiple API requests in parallel to update a specific Smartsheet object will result in reduced performance and will often result 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 (i.e., execute one request at time, not beginning the next request until the previous request has completed).

Errors

A successful error handling strategy requires that your integration recognize the difference between errors that can potentially be resolved by retrying the request and errors that should never be retried automatically. The HTTP status code that is returned with each response is your first indication as to the outcome of the request. Message content is returned as raw text. You may need to escape it if displayed in HTML.

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.

Examples:
  • 400 Bad Request
  • 401 Not Authorized
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not Supported
  • 406 Not Acceptable
  • 415 Unsupported Media Type
  • 429 Too Many Requests
Never automatically retry the request.

If the error code indicates a problem that can be fixed, fix the problem and then retry the request.

See Error Handling for error handling recommendations by error code.
5xx The request was properly formatted, but the operation failed on Smartsheet’s end.

Examples:
  • 500 Internal Server Error
  • 503 Service Unavailable
In some scenarios, requests should be automatically retried using exponential backoff.

In other cases, requests should not be retried.

See Error Handling for error handling recommendations by error code.



In addition to the HTTP status code, you should also evaluate the Smartsheet-specific error code that’s returned in the response body for any unsuccessful request. All errors will also be accompanied by JSON-formatted error objects, containing a Smartsheet-specific error code and a descriptive message. For example, doing a GET on a non-existent sheet at https://api.smartsheet.com/2.0/sheets/123456 will result in an HTTP status code of 404, indicating the resource was not found. The body of the response will include an Error object:

{
    “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 will be noted in the specific API operation for which the error may occur.

See Error Handling for detailed error handling recommendations.

Error Handling

The following table specifies the recommended action for each Smartsheet-specific error code. Use this information to implement error handling logic according to the following guidelines:

  • If the error code indicates a permanent error condition, do not retry the request.
  • If the error code indicates a problem that can be fixed, do not retry the request until the problem has been fixed.
  • If the error code indicates a problem that could be overcome by retrying the request after a period of time, retry the request using exponential backoff.
HTTP status code Smartsheet errorCode Smartsheet message Recommended Action
401 1001 An Access Token is required. Do not retry without fixing the problem.

Hint: Verify that Authorization header is present and set properly.
401 1002 Your Access Token is invalid. Do not retry without fixing the problem.

Hint: Verify that the access token specified in the Authorization header is valid.
401 1003 Your Access Token has expired. Do not retry without fixing the problem.

Hint: Generate a new access token or refresh the token.
403 1004 You are not authorized to perform this action. Do not retry without fixing the problem.

Hint: Verify that Authorization header is present and set properly, and that the requester has the required permission level in Smartsheet to perform the requested action.
401 1005 Single Sign-On is required for this account. Do not retry.
404 1006 Not Found. Do not retry without fixing the problem.

Hint: Verify that specified URI is correct. If the URI contains an object ID, verify that the object ID is correct and that the requester has access to the corresponding object in Smartsheet.
404 1007 Version not supported. Do not retry without fixing the problem.
400 1008 Unable to parse request. The following error occurred: {0} Do not retry without fixing the problem.
400 1009 A required parameter is missing from your request: {0}. Do not retry without fixing the problem.
405 1010 HTTP Method not supported. Do not retry without fixing the problem.

Hint: Verify that the proper verb is specified for the request (GET, PUT, POST, or DELETE).
400 1011 A required header was missing or invalid: {0} Do not retry without fixing the problem.
400 1012 A required object attribute is missing from your request: {0}. Do not retry without fixing the problem.
403 1013 The operation you are attempting to perform is not supported by your plan. Do not retry without fixing the problem.
403 1014 There are no licenses available on your account. Do not retry without fixing the problem.
403 1015 The user exists in another account. The user must be removed from that account before they can be added to yours. Do not retry without fixing the problem.
403 1016 The user is already a member of your account. Do not retry.
403 1017 The user already has a paid account. The user must cancel that account before they can be added to yours. Do not retry without fixing the problem.
400 1018 The value {0} was not valid for the parameter {1}. Do not retry without fixing the problem.
400 1019 Cannot transfer to the user specified. User not found. Do not retry without fixing the problem.

Hint: Verify that the transferTo User ID specified is correct.
404 1020 User not found. Do not retry without fixing the problem.

Hint: Verify that the User ID specified is correct.
403 1021 Cannot transfer to the user specified. They are not a member of your account. Do not retry.
403 1022 Cannot delete the user specified. They are not a member of your account. Do not retry.
400 1023 The sheet specified is shared at the Workspace level. Do not retry.
400 1024 The HTTP request body is required for this Method. Do not retry without fixing the problem.
400 1025 The share already exists. Do not retry.
403 1026 Transferring ownership is not currently supported. Do not retry.
404 1027 Share not found. Do not retry without fixing the problem.

Hint: Verify that the Share ID specified is correct.
400 1028 You cannot edit the share of the owner. Do not retry.
400 1029 The parameter in the URI does not match the object in the request body. Do not retry without fixing the problem.
401 1030 You are unable to assume the user specified. Do not retry.
400 1031 The value {0} was not valid for the attribute {1}. Do not retry without fixing the problem.
400 1032 The attribute(s) {0} are not allowed for this operation. Do not retry without fixing the problem.
404 1033 The template was not found. Do not retry without fixing the problem.

Hint: Verify that the Template ID specified is correct.
400 1034 Invalid Row ID. Do not retry without fixing the problem.
400 1035 Attachments and discussions cannot be POSTed with a row. Do not retry without fixing the problem.
400 1036 The columnId {0} is invalid. Do not retry without fixing the problem.
400 1037 The columnId {0} is included more than once in a single row. Do not retry without fixing the problem.
400 1038 Invalid Cell value. Must be numeric or a string. Do not retry without fixing the problem.
403 1039 Cannot edit a locked column {0} Do not retry.
400 1040 Cannot edit your own share. Do not retry.
400 1041 The value for {0} must be {1} characters in length or less, but was {2}. Do not retry without fixing the problem.
400 1042 The value for cell in column {0}, {1}, did not conform to the strict requirements for type {2}. Do not retry without fixing the problem.
404 1043 The row number you requested is blank and cannot be retrieved. Do not retry without fixing the problem.
400 1044 Assume-User header is required for your Access Token. Do not retry without fixing the problem.
403 1045 The resource specified is read-only. Do not retry.
400 1046 Cells containing formulas, links to other cells, system values, or Gantt values cannot be inserted or updated through the API. Do not retry.
403 1047 You cannot remove yourself from the account through the API. Do not retry.
403 1048 The user specified has declined the invitation to join your organization. You cannot modify declined invitations. Do not retry.
403 1049 You cannot remove admin permissions from yourself through the API. Do not retry.
403 1050 You cannot edit a locked row. Do not retry.
400 1051 Attachments of type FILE cannot be created using JSON. Do not retry without fixing the problem.
406 1052 Invalid Accept header. Media type not supported. Do not retry without fixing the problem.

Hint: Verify that Accept header is set to the proper value (to match the output of the invoked endpoint – typically “application/json”).
400 1053 Unknown Paper size: {0}. Do not retry without fixing the problem.
400 1054 The new sheet requires either a fromId or columns. Do not retry without fixing the problem.
400 1055 One and only one column must be primary. Do not retry without fixing the problem.
400 1056 Column titles must be unique. Do not retry without fixing the problem.
400 1057 Primary columns must be of type TEXT_NUMBER. Do not retry without fixing the problem.
400 1058 Column type of {1} does not support symbol of type {0}. Do not retry without fixing the problem.
400 1059 Column options are not allowed when a symbol is specified. Do not retry without fixing the problem.
400 1060 Column options are not allowed for column type {0}. Do not retry without fixing the problem.
400 1061 Max count exceeded for field {0}. Do not retry without fixing the problem.
400 1062 Invalid row location. Do not retry without fixing the problem.
400 1063 Invalid parentId: {0}. Do not retry without fixing the problem.
400 1064 Invalid siblingId: {0}. Do not retry without fixing the problem.
400 1065 The column specified cannot be deleted. Do not retry.
400 1066 You can only share to {0} users at a time. Do not retry without fixing the problem.

Hint: Reduce the number of users specified in the Share request.
401 1067 Invalid client_id Do not retry without fixing the problem.

Hint: Verify that the value of the client_id querystring parameter matches the value of the App client Id shown in the Smartsheet web UI (Developer Tools >> App Profile).
400 1068 Unsupported grant type. Do not retry without fixing the problem.

Hint: Verify that the value of the grant_type querystring parameter is “authorization_code”.
400 1069 Invalid Request. The authorization_code has expired. Do not retry without fixing the problem.

Hint: Repeat step 1 of the OAuth flow (to retrieve a new authorization code).
400 1070 Invalid Request. Required parameter is missing: {0}. Do not retry without fixing the problem.
400 1071 Invalid Grant. The authorization code or refresh token provided was invalid. Do not retry without fixing the problem.
400 1072 Invalid hash value. The hash provided did not match the expected value. Do not retry without fixing the problem.
400 1073 The redirect_uri did not match the expected value. Do not retry without fixing the problem.

Hint: Omit the redirect_uri querystring parameter – if redirect_uri is not specified in the querystring, the value specified in the Smartsheet web UI (Developer Tools >> App Profile) will be used by default.
400 1074 You are trying to upload a file of {0}, but the API currently only supports {1} Do not retry without fixing the problem.
400 1075 The Content-Size provided did not match the file uploaded. This may be due to network issues or because the wrong Content-Size was specified. Do not retry without fixing the problem.
403 1076 The user has created sheets and must be added as a licensed user. Do not retry without fixing the problem.
400 1077 Duplicate system column type: {0}. Do not retry without fixing the problem.
400 1078 System column type {0} not supported for {1} {2}. Do not retry without fixing the problem.
400 1079 Column type {0} is not supported for system column type {1} Do not retry without fixing the problem.
400 1080 End Dates on dependency-enabled sheets cannot be created/updated. Please update either the Duration or Start Date column. Do not retry.
403 1081 You cannot delete another user’s discussions, comments, or comment attachments. Do not retry.
400 1082 You cannot add options to the given column {0} because it is not a PICKLIST. Do not retry without fixing the problem.
400 1083 Auto number formatting cannot be added to a column {0} Do not retry without fixing the problem.
400 1084 The auto number format is invalid. Do not retry without fixing the problem.
400 1085 To change this column’s type you must first disable Dependencies for this sheet. Do not retry without fixing the problem.
400 1086 Google was not able to verify your access. Do not retry without fixing the problem.
400 1087 The column specified is used in a conditional formatting rule, so the column cannot be deleted and its type cannot be changed. Do not retry without fixing the problem.
400 1088 Invalid length for concatenated auto number format. Concatenated format is {0}, with a length of {1}. Must be less than or equal to 40. Do not retry without fixing the problem.
400 1089 The type specified is only used with System Columns. Do not retry without fixing the problem.
400 1090 Column.type is required when changing symbol, systemColumnType or options. Do not retry without fixing the problem.
400 1091 Invalid Content-Type: {0} Do not retry without fixing the problem.
403 1092 You cannot delete this row. Either it or one or more of its children are locked. Do not retry.
400 1095 The Excel file is invalid/corrupt. This may be due to an invalid file extension, an outdated Excel format, or an invalid Content-Length. Do not retry without fixing the problem.
403 1096 This Apple payment receipt has already been applied to a user’s payment profile. Do not retry.
403 1097 A user must be a licensed sheet creator to be a resource viewer. Do not retry without fixing the problem.
400 1098 To delete this column you must first disable Dependencies for this sheet. Do not retry without fixing the problem.
400 1099 To delete this column you must first disable Resource Management for this sheet. Do not retry without fixing the problem.
400 1100 Uploading new versions of a discussion comment attachment is not supported. Do not retry.
400 1101 Uploading new versions of non-FILE type attachments is not supported. Do not retry.
403 1102 A user must be a licensed sheet creator to be a group administrator. Do not retry without fixing the problem.
400 1103 A group with the same name already exists. Do not retry without fixing the problem.
403 1104 You must be a group administrator to create a group. Do not retry without fixing the problem.

Hint: Verify that the requester has “Group Admin” permissions in Smartsheet.
400 1105 The operation failed because one or more group members were not members of your account: {0} Do not retry without fixing the problem.
404 1106 Group not found Do not retry without fixing the problem.

Hint: Verify that specified Group ID is correct.
400 1107 User specified in transferGroupsTo must be a group admin. Do not retry without fixing the problem.
400 1108 transferGroupsTo must be provided because user being deleted owns one or more groups. Do not retry without fixing the problem.
400 1109 Only one of cell.hyperlink or cell.linkInFromCell may be non-null. Do not retry without fixing the problem.
400 1110 cell.value must be null if cell.linkInFromCell is non-null. Do not retry without fixing the problem.
400 1111 Only one of cell.hyperlink.sheetId and cell.hyperlink.reportId may be non-null. Do not retry without fixing the problem.
400 1112 cell.hyperlink.url must be null for sheet or report hyperlinks. Do not retry without fixing the problem.
400 1113 cell.value must be a string when the cell is a hyperlink. Do not retry without fixing the problem.
404 1114 Invalid sheetId or reportId: {0} Do not retry without fixing the problem.
400 1115 Row must contain either cell link updates or row/cell value updates; mixing of both update types in one API call is not supported. Do not retry without fixing the problem.
400 1116 You cannot link a cell to its own sheet. Do not retry.
400 1117 One of the following cell.hyperlink fields must be non-null: url, sheetId, or reportId. Do not retry without fixing the problem.
400 1118 You cannot set the value of a Gantt allocation column (id {0}) in a row that has child rows. Do not retry.
500 1119 Failed to complete copy.
NOTE: may include a “detail” object containing “topContainerType” and “topContainerId” which represent the top-level folder or workspace that were partially copied.
Do not retry.
400 1120 Too many sheets to copy.
NOTE: includes a “detail” object containing “maxSheetCount” which represents the server-side limit on the number of sheets allowed in a single folder/workspace copy operation.
Do not retry without fixing the problem.

Hint: Reduce number of sheets being copied to maxSheetCount or fewer before reattempting the request.
400 1121 transferTo must be provided because user being deleted owns one or more groups. Do not retry without fixing the problem.
405 1122 Requested URL does not support this method: {0} Do not retry without fixing the problem.

Hint: Verify that the verb specified for the request (GET, POST, PUT, DELETE) is valid for the specified URI.
400 1123 Specifying multiple row locations is not yet supported. Each row must use the same row location attribute and value (toBottom, toTop, parentId, siblingId, above) Do not retry without fixing the problem.
415 1124 Invalid Content-Type header. Media type not supported. Do not retry without fixing the problem.

Hint: Verify that Content-Type header is specified and set to the proper value.
400 1125 Each part in a multipart payload must have a name Do not retry without fixing the problem.
400 1126 Multipart payload contained duplicate part names: {0} Do not retry without fixing the problem.
400 1127 Required multipart part was missing: ’{0}’ Do not retry without fixing the problem.
400 1128 Multipart upload size limit exceeded. Do not retry without fixing the problem.
400 1129 The resource you tried to create already exists. Do not retry.
400 1130 One of cell.value or objectValue may be set, but not both. Do not retry without fixing the problem.
400 1131 cell.{0} for column {1} was of the wrong object type. Allowed types: {2} Do not retry without fixing the problem.
400 1132 The token provided has previously been revoked. Do not retry.

Hint: This error occurs during the OAuth flow when trying to refresh a token that’s previously been revoked. Must instead obtain a new token.
400 1133 Column titles are not unique among input columns. Do not retry without fixing the problem.
400 1134 Duplicate system column type among input columns. Do not retry without fixing the problem.
400 1135 Input column index {0} is different from the first input column index {1}. Do not retry without fixing the problem.
400 1136 Cannot copy or move row(s) within the same sheet. Do not retry.
400 1137 Input collection contains multiple instances of the same element. Do not retry without fixing the problem.
403 1138 The user is not eligible for a trial organization. Do not retry.
403 1139 The user is an admin in another organization. Add ‘allowInviteAccountAdmin=true’ to the query string to invite their entire organization. Do not retry without fixing the problem.
403 1140 The user must be added as a licensed user. Do not retry without fixing the problem.
403 1141 Inviting users from an enterprise organization is not supported. Do not retry.
400 1142 Column type {0} is reserved for project sheets and may not be manually set on a column. Do not retry without fixing the problem.
400 1143 To set {0}, you must first enable dependencies on the sheet. Do not retry without fixing the problem.
400 1144 The user owns one or more groups and must be added as a Group Admin. Do not retry without fixing the problem.
400 1145 Multipart upload request was invalid. Please check your request headers and payload. Do not retry without fixing the problem.
400 1146 Unsupported operation: {0}. Do not retry.
400 1147 Multipart request contained an invalid part name: ’{0}’ Do not retry without fixing the problem.
400 1148 Numeric cell values must be between {0} and {1}. Do not retry without fixing the problem.
400 1155 You cannot set the ’{0}’ attribute for a cell in a 'Project Settings’ column of a dependency-enabled sheet. Do not retry.
400 1156 Invalid email Do not retry without fixing the problem.

Hint: Verify that the email address is properly formatted.
400 1157 This address is already associated with another Smartsheet account, so it cannot be added as an alternate address for this account. Do not retry.
400 1158 This address has not been confirmed yet, so it can’t be set as the primary email address. Do not retry without fixing the problem.
400 1159 The specified email address ({0}) is an alternate email address for a user with a primary email address of {1}. Do not retry without fixing the problem.
400 1160 Invalid bulk request. See detail for more information. Do not retry without fixing the problem.

Hint: Examine the detail attribute within the error response for details about the issue(s).
400 1161 Cannot set altText for a cell that does not contain an image: row {0}, column {1}. Do not retry.
400 1163 If cell.image is non-null then value, objectValue, hyperlink, and linkInFromCell must all be null. Do not retry without fixing the problem.
400 1164 Cannot add image to cell because this feature has been disabled by the org administrator. Do not retry.
400 1165 Cannot add image to cell with alt text larger than 100 characters. Do not retry without fixing the problem.
400 1166 You cannot share Sights as an Editor. Do not retry.
400 1167 The resource you are attempting to access has expired. Do not retry.
500 1170 The sheet referenced by this widget is unavailable or deleted. Do not retry.
500 1171 The report referenced by this widget is unavailable or deleted. Do not retry.
500 1172 The referenced cell is unavailable or deleted. Do not retry.
403 1173 You must be in a Team/Enterprise account to specify a {0} value of ’{1}’. Do not retry.
403 1174 The value for {0} is invalid because this publish option is configured to be restricted to users in this account. Do not retry.
403 1175 One or more publish options which you attempted to enable are disabled for this account. Do not retry.
400 1176 Array attribute(s) may not contain null elements: {0}. Do not retry without fixing the problem.
400 1177 Arrays may not contain null elements. Do not retry without fixing the problem.
400 1178 The following combination of attributes is not allowed for this operation: {0}. Do not retry without fixing the problem.

Hint: Examine the detail attribute(s) within the error response for detail about the issue(s).
400 1179 The schedule specified is invalid because endAt is earlier than the next send date. Do not retry without fixing the problem.

Hint: Verify that startAt, endAt, repeatEvery and other attributes will result in one or more future delivery.
500 4000 An unexpected error has occurred. Please contact api@smartsheet.com for assistance. Do not retry.
503 4001 Smartsheet.com is currently offline for system maintenance. Please check back again shortly. Retry using exponential backoff.

Hint: Wait time between retries should measure in minutes (not seconds).
500 4002 Server timeout exceeded. Request has failed. Retry using exponential backoff.
429 4003 Rate limit exceeded. Retry using exponential backoff.

Hint: Reduce the rate at which you are sending requests.
500 4004 An unexpected error has occurred. Please retry your request. If you encounter this error repeatedly, please contact api@smartsheet.com for assistance.

Or

Request failed because sheetId {0} is currently being updated by another request that uses the same access token. Please retry your request once the previous request has completed.
Retry using exponential backoff.
400 5xxx Errors in the 5xxx range represent conditions that a developer cannot reasonably prevent or handle, most typically related to account status. These error messages are localized and can be displayed to the end-user to inform them of the condition that caused the error to occur. Do not retry.

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

  • STAR
  • FLAG

Symbols for PICKLIST columns:

  • HARVEY_BALLS
  • PRIORITY
  • RYG
  • PRIORITY_HML
  • DECISION_SYMBOLS
  • DECISION_SHAPES
  • VCR
  • RYGB
  • RYGG
  • WEATHER
  • PROGRESS
  • ARROWS_3_WAY
  • ARROWS_4_WAY
  • ARROWS_5_WAY
  • DIRECTIONS_3_WAY
  • DIRECTIONS_4_WAY
  • SKI
  • SIGNAL
  • STAR_RATING
  • HEARTS
  • MONEY
  • EFFORT
  • PAIN

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 will include an AutoNumberFormat object that describes the mask used to generate the value.

Cell Values

Within the Smartsheet web application, all editable column types are flexible and cells in those columns can contain either a value specific to the column type (e.g. dates, checkboxes, symbols, etc.) or a free-form text value. This allows for a very flexible UI and is one of the key benefits to using Smartsheet.

Cell Value Representation

Cell objects retrieved through the Smartsheet API’s 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 will return error code 1042.

If, however, you want the same flexibility as the Smartsheet web application, 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”) will be 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 will be 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 We will attempt 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, we will recognize the date and store 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, we use that as the name, otherwise if we find a match among the the Access Token owner’s contacts, we will associate this cell with that existing contact.
Lenient If the value is a valid email address, we handle it the same way as Strict. If not, we save 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 We will attempt 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, we will recognize the date and store 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 will display the value provided.
  • If displayValue is an empty string, the Smartsheet cell will display the email address.
  • If displayValue is null or absent, Smartsheet will make a best guess effort at filling it in with a contact’s name based on the email address.

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:

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.
includeAll boolean If true, include all results (i.e. 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.
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.

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 mulitple objects in a single request, which we recommend as a best practice for optimal performance.

The following API operations currently allow you to do things in bulk:

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 will contain 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 will be noted as such in their API reference documentation.

NOTE: Several POST operations fail when attempting to create a single object which already exists (e.g. favorites, shares, group members). However, for the corresponding bulk operations, these endpoints will not return an error if one or more items in the array already exist. Existing items will simply be ignored, and Result object returned will omit 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, all objects in the request will be created/updated/deleted; if not, none of them will be.

However, there are some operations that support partial success, which means the operation will still succeed even if one or more of the objects in the request failed for some reason (e.g. an object is invalid). Partial success is typically not the default mode for an operation, and instead must be explicitly enabled by using a query string parameter. This will be 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 will contain 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.

Dates and Times

The Smartsheet API returns all dates and times in the UTC time zone, in ISO-8601 format. If a date/time needs to be displayed to an end-user in their local time zone, you will need to 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 input 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.

Getting Started

Developer Account

Developer accounts provide access to the full range of features and functionality available in production. They are easy to set up, will not expire, and will let you focus on your development without any risk to your production data.

To set up a Developer account, please visit the Smartsheet Developer Portal registration page. If you already have a paid Smartsheet account and your goal is to keep your development and production accounts separate, make sure to use a different email address when registering.

Please note that Developer accounts are intended for development and testing purposes only, and are subject to the Smartsheet Developer Program Agreement.

SDKs and Sample Code

Smartsheet SDKs (client libraries) are available in a variety of languages. For the complete list, see our SDK page. Submit your vote for additional language coverage by emailing us at api@smartsheet.com.

This API documentation currently contains sample code in the following languages:

  • cURL
  • C#
  • Java
  • Node.js
  • Python

For each operation, you’ll see sample code displayed in the dark blue panel next to the operation. To view the sample code in a specific language, select the corresponding language tab along the top of the dark blue panel. Each C#, Java, and Node.js code sample demonstrates how to execute an operation using the corresponding Smartsheet SDK. See the corresponding section below for more information about using the sample code in a specific language.

cURL Sample Code

# For cURL code samples, see each operation in the API REFERENCE section.

The cURL code samples included in this API documentation demonstrate how to execute operations using the command line data transfer tool cURL.

C# Sample Code

using Smartsheet.Api;
using Smartsheet.Api.Models;
using Smartsheet.Api.OAuth;

// Set the Access Token.
Token token = new Token();
token.AccessToken = "INSERT_YOUR_TOKEN_HERE";

// Use the Smartsheet Builder to create an instance of SmartsheetClient.
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).Build();

// Get current user.
smartsheet.UserResources.GetCurrentUser();

// Get server info.
smartsheet.ServerInfoResources.GetServerInfo();

// For additional C# code samples, see each operation in the API REFERENCE section.

The C# code samples included in this API documentation demonstrate how to execute operations using the Smartsheet C# SDK. To use the C# SDK, you’ll need to include the appropriate using directives in your code. For example:

using Smartsheet.Api;
using Smartsheet.Api.Models;
using Smartsheet.Api.OAuth;

Each code sample uses a SmartsheetClient object called “smartsheet” that can be created as follows:

// Set the Access Token
Token token = new Token();
token.AccessToken = "INSERT_YOUR_TOKEN_HERE";

// Use the Smartsheet Builder to create an instance of SmartsheetClient
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).Build();

For operations that support querystring parameters, the C# code sample often contains multiple example requests, each one showing a different combination of querystring parameters. The code samples are intended for example purposes only and should not be considered to cover all possible combinations of querystring parameters.

Within the C# code samples, the …Id naming convention is used to denote an object ID that will need to be replaced with an actual object ID, should you use the code in your application. For example, in the following code example, sheetId should be replaced with the actual ID of the Sheet and rowId should be replaced with the actual ID of the Row:

smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussion(sheetId, rowId, discussion);

Java Sample Code

import com.smartsheet.api.*;
import com.smartsheet.api.models.*;
import com.smartsheet.api.models.enums.*;
import com.smartsheet.api.oauth.*;

// Set the Access Token.
Token token = new Token();
token.setAccessToken("INSERT_YOUR_TOKEN_HERE");

// Use the Smartsheet Builder to create an instance of Smartsheet.
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(token.getAccessToken()).build();

// Get current user.
smartsheet.userResources().getCurrentUser();

// Get server info.
smartsheet.serverInfoResources().getServerInfo();

// For additional Java code samples, see each operation in the API REFERENCE section.

The Java code samples included in this API documentation demonstrate how to execute operations using the Smartsheet Java SDK. To use the Java SDK, you’ll need to include the appropriate import directives in your code. For example:

import com.smartsheet.api.*;
import com.smartsheet.api.models.*;
import com.smartsheet.api.models.enums.*;
import com.smartsheet.api.oauth.*;

Each code sample uses a Smartsheet object called “smartsheet” that can be created as follows:

// Set the Access Token
Token token = new Token();
token.setAccessToken("INSERT_YOUR_TOKEN_HERE");

// Use the Smartsheet Builder to create an instance of Smartsheet
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(token.getAccessToken()).build();

For operations that support querystring parameters, the Java code sample often contains multiple example requests, each one showing a different combination of querystring parameters. The code samples are intended for example purposes only and should not be considered to cover all possible combinations of querystring parameters.

Within the Java code samples, the …Id naming convention is used to denote an object ID that will need to be replaced with an actual object ID, should you use the code in your application. For example, in the following code example, sheetId should be replaced with the actual ID of the Sheet and rowId should be replaced with the actual ID of the Row:

smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(sheetId, rowId, discussion);

Node.js Sample Code

var client = require('smartsheet');
var smartsheet = client.createClient({accessToken:'INSERT_YOUR_TOKEN_HERE'});

// Get current user.
smartsheet.users.getCurrentUser()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });

// Get server info.
smartsheet.server.getInfo()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });

// For additional Node.js code samples, see each operation in the API REFERENCE section.

The Node.js code samples included in this API documentation demonstrate how to execute operations using the Smartsheet JavaScript SDK, with promises. Each code sample uses a root module called “smartsheet” that can be created as follows:

var client = require('smartsheet');
var smartsheet = client.createClient({accessToken:'INSERT_YOUR_TOKEN_HERE'});

Once you’ve created the smartsheet variable, you can use it to execute API operations. For example, the following code example shows how to execute the Get Current User operation.

smartsheet.users.getCurrentUser()
  .then(function(data) {
    console.log(data);
  })
  .catch(function(error) {
    console.log(error);
  });

For more information about using the Smartsheet JavaScript SDK, including examples of using callbacks (instead of promises), see the SDK Readme.

Python Sample Code

import smartsheet
smartsheet = smartsheet.Smartsheet()

# Get Current User
me = smartsheet.Users.get_current_user()
print(me)

# Get server info.
info = smartsheet.Server.server_info()

# For additional Python code samples, see each operation in the API REFERENCE section.

The Python samples included in this API documentation demonstrate how to execute operations using the Smartsheet Python SDK. To use the Python SDK, you’ll first need to include the appropriate import directive in your code:

import smartsheet

Next, create the base client object that will be used to execute API requests via the SDK:

smartsheet = smartsheet.Smartsheet()

Once you’ve created the smartsheet object, you can use it to execute API operations. For example, the following example shows how to execute the Get Current User operation.

me = smartsheet.Users.get_current_user()
print(me)

Within the Python code samples, the …Id naming convention is used to denote an object ID that will need to be replaced with an actual object ID, should you use the code in your application. For example, in the following code example, sheetId should be replaced with the actual ID of the Sheet and rowId should be replaced with the actual ID of the Row:

smartsheet.Discussions.create_discussion_on_row(
    sheetId,
    rowId,
    smartsheet.models.Discussion({
        'title': 'Expense Reimbursement',
        'comment': smartsheet.models.Comment({
            'text': 'Expenses greater than $500 require manager approval.'
        })
    })
)

Direct API Access

Smartsheet makes it easy to directly access your data via the API. The first step is to generate an Access Token via the Smartsheet UI. Users can generate and have more than one active token at any time. Access Tokens generated in Smartsheet UI are long lived, meaning they won’t expire for 10 years. They are best used in system-level integrations, such as applications designed to keep Smartsheet and other systems in sync, or to integrate with Zapier, ifttt or similar API integration services.

Generating Access Token

These instructions assume that you already have an existing Smartsheet account. Follow these steps to generate an Access Token:

  1. Click the Account button in the upper-left corner of your Smartsheet screen and select Personal Settings. This will open the Personal Settings form.
  2. Click the API Access button to open the API Access form.
  3. Use the API Access form to generate new or manage existing acces tokens.

Because you can generate and have more than one active token at any time, you have the ability to implement a granular security policy by designating a separate token for each application or integration scenario you may have. That way, should any one token become compromised, you can easily revoke it without impacting any of your other API-enabled applications.

Using Access Tokens

Example Request:

curl https://api.smartsheet.com/2.0/users/me \
`-H "Authorization: Bearer ACCESS_TOKEN"
// Set the access token.
var client = require('smartsheet');
var smartsheet = client.createClient({accessToken:'INSERT_YOUR_TOKEN_HERE'});

// Get current user.
smartsheet.users.getCurrentUser()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// Set the access token.
Token token = new Token();
token.AccessToken = "INSERT_YOUR_TOKEN_HERE";
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).Build();

// Get current user.
smartsheet.UserResources.GetCurrentUser();
// Set the access token.
Token token = new Token();
token.setAccessToken("INSERT_YOUR_TOKEN_HERE");
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(token.getAccessToken()).build();

// Get current user.
smartsheet.userResources().getCurrentUser();
# Create base client object and set the access token.
smartsheet = smartsheet.Smartsheet('INSERT_YOUR_TOKEN_HERE')

# Get current user.
smartsheet.Users.get_current_user()

Example Response:

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

Once you have an Access Token, include it in the Authorization header for every request you make:

Authorization: Bearer 0da6cf0d848266b4cd32a6151b1

The header name is Authorization and the value of the header is Bearer ACCESS_TOKEN, where ACCESS_TOKEN is a token generated by you. Since the access token is being transmitted in clear text, all API calls are done over HTTPS.

Third Party App Development

In addition to being a powerful work management tool, Smartsheet is a powerful application platform. We are committed to making it easy to build applications on top of Smartsheet - whether you are developing a solution for your organization or creating an app for the Smartsheet customer community at large. We are here to support you and would love your feedback on how to improve the API and the developer experience.

As a developer, you may be building applications that allow any Smartsheet user to access his or her Smartsheet data. Doing so requires that you complete the following steps.

  1. Complete your Developer Profile
  2. Register your App
  3. Within your app, implement a 3-legged OAuth flow to obtain an access token that can be used to access Smartsheet data on behalf of an end user.

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, you should see a new Developer Tools option in the dropdown menu. Select it to open Developer Tools.
  3. Before you can register your first app, you will need to 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 will be able to use Developer Tools to register and manage your apps.

Registering 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 select 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

In order 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 will be performing. Access Scopes do not override existing Access Level restrictions. For example, having the Access Scope of WRITE_SHEETS will not allow your app to update a sheet on which the end user has read-only permission.

The Access Scopes are as follows:

READ_SHEETS Read all sheet data, including comments, attachments and cell data
WRITE_SHEETS Insert and modify sheet data, including comments, attachments and cell data
SHARE_SHEETS Share sheets, including sending sheets as attachments
DELETE_SHEETS Delete sheets
CREATE_SHEETS Create new sheets
CREATE_SIGHTS Create new sights
READ_SIGHTS Read all sight data
DELETE_SIGHTS Delete sight
SHARE_SIGHTS Share sight
READ_USERS Retrieve users and groups for your Smartsheet organization
READ_CONTACTS Retrieve contacts
ADMIN_USERS Add and remove users from your Smartsheet organization; create groups and manage membership
ADMIN_SHEETS Modify sheet structure, including column definition, publish state, etc.
ADMIN_SIGHTS Modify sight structure
ADMIN_WORKSPACES Create and manage workspaces and folders, including sharing

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. This process involves the following steps:

  1. Request authorization from the user
  2. Obtain the authorization code
  3. Use the authorization code to obtain an access token
  4. Refresh the access token (as necessary)

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

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, e.g. “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 arbitrary string that will be 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, your user will be prompted to allow or deny the access scopes you requested.

Obtaining the authorization code

If the user clicks “Allow”, he/she will be redirected to the redirect_uri with the following parameters:

code authorization code required to obtain access token
expires_in number of seconds code is valid once issued; this is always 4 minutes - you must obtain an access token within that time
state state string specified earlier

If the user clicks “Deny”, he/she will be redirected to the redirect_uri with the following parameters:

error “access_denied”
state state string specified earlier

Other errors that may be returned include:

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

Obtaining 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
// [todo]
// [todo]
// [todo]
# [todo]

Successful Response:

{
   "access_token": "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, you’ll need to make a POST request to https://api.smartsheet.com/2.0/token with the following parameters:

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 (e.g., “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.

Possible OAuth error types:

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

Refreshing 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
// [todo]
// [todo]
// [todo]
# [todo]

Successful Response:

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

An access token is valid for one week but you can use the refresh token to obtain a new access token. Once you obtain the new access token, you can use it in place of the old one, which is no longer valid.

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

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 (e.g., “http://”)
hash
(required)
SHA-256 hash of your App secret concatenated with a pipe and the refresh token value
Getting 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.

Admin Features

Smartsheet users with System Admin rights have access to additional API features, including user management and ability to access any sheet in the organization.

Manage Users

As an org Administrator, you can provision, de-provision and otherwise manage users in your Smartsheet organization. See Users for more information on relevant API calls.

Assume-User

Example Request:

curl https://api.smartsheet.com/2.0/users/me \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Assume-User: john.doe%40smartsheet.com" 
// [todo]
// Create the 'smartsheet' object and set the 'Assume-User' header value to "john.doe@smartsheet.com".
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).SetAssumedUser("john.doe@smartsheet.com").Build();

// Get current user (call gets executed as "john.doe@smartsheet.com").
UserProfile userProfile = smartsheet.UserResources.GetCurrentUser();
// Create the 'smartsheet' object and set the 'Assume-User' header value to "john.doe@smartsheet.com".
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(accessToken).setAssumedUser("john.doe@smartsheet.com").build();

// Get current user (call gets executed as "john.doe@smartsheet.com").
UserProfile user= smartsheet.userResources().getCurrentUser();
# Create the 'smartsheet' object and run the assume_user method.
smartsheet = smartsheet.Smartsheet()
smartsheet.assume_user('john.doe@smartsheet.com')

# Get the current user (call executed as "john.doe@smartsheet.com").
user = smartsheet.Users.get_current_user()

# Reset the 'smartsheet' object so no Assume-User header is used in further requests.
smartsheet.assume_user()

Example Response:

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

As an org Administrator, you can assume the identity of any user in your organization. This advanced feature enables a number of useful business scenarios, such as executing an organization-wide backup or maintaining data attribution when integrating with another system.

Here is how it works. Simply add an Assume-User header to your call, with the URI-encoded email address of the user whose identity you want to assume as the value. For example, if you want to assume the identity of john.doe@smartsheet.com and john.doe@smartsheet.com is a confirmed member of your Smartsheet organization, you would add the following header:

Assume-User: john.doe%40smartsheet.com

You can then act on behalf of the user and make API calls as though you were that user.

Maintain Data Attribution

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Assume-User: john.doe%40smartsheet.com" \
-H "Content-Type: application/json" \
-X POST \
-d '{"text":"This is a new comment."}'
// [todo]
// Create the 'smartsheet' object and set the 'Assume-User' header value to "john.doe@smartsheet.com".
SmartsheetClient smartsheet = new SmartsheetBuilder().SetAccessToken(token.AccessToken).SetAssumedUser("john.doe@smartsheet.com").Build();

// Create comment.
Comment comment = new Comment.AddCommentBuilder("This is a new comment.").Build();

// Add comment to discussion (call gets executed as "john.doe@smartsheet.com").
smartsheet.SheetResources.DiscussionResources.CommentResources.AddComment(sheetId, discussionId, comment);
// Create the 'smartsheet' object and set the 'Assume-User' header value to "john.doe@smartsheet.com".
Smartsheet smartsheet = new SmartsheetBuilder().setAccessToken(accessToken).setAssumedUser("john.doe@smartsheet.com").build();

// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This is a new comment.").build();

// Add comment to discussion (call gets executed as "john.doe@smartsheet.com").
smartsheet.sheetResources().discussionResources().commentResources().addComment(sheetId, discussionId, comment);
# Create the 'smartsheet' object and run the assume_user method.
smartsheet = smartsheet.Smartsheet()
smartsheet.assume_user('john.doe@smartsheet.com')

# Create comment.
comment = smartsheet.models.Comment({
    'text': 'Expense reports require manager approval.'
})

# Add comment to discussion (call executed as "john.doe@smartsheet.com").
smartsheet.Discussions.add_comment_to_discussion(sheetId, discussionId, 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
}

If you are integrating Smartsheet with another API-enabled system, such as Salesforce, it may be useful to maintain attribution when adding data to Smartsheet. For example, let’s say you want to add a new row to a Sales Pipeline sheet in Smartsheet whenever your sales team updates a sales pipeline in Salesforce. So, if Bob Johnson makes a change in Salesforce, wouldn’t it be great to make the new row show up in Smartsheet as if it were created by Bob? Specifying the Assume-User header API requests allows org Administrators to develop integrations which do just that.

List All Sheets

As an org Administrator, you can get a list of all sheets in your organization, regardless of ownership or whether or not the sheets have been shared to you. Please see List All Org Sheets for more information.

Backup All Org Data

Get list of all sheets in the org:

curl https://api.smartsheet.com/2.0/users/sheets \
-H "Authorization: Bearer ACCESS_TOKEN"
smartsheet.sheets.listOrganizationSheets()
    .then(function(data) {
        console.log(data)
    })
    .catch(function(error) {
        console.log(error);
    });
// List all org sheets.
smartsheet.UserResources.SheetResources.ListSheets();
// List all org sheets.
smartsheet.userResources().listOrgSheets();
action = smartsheet.Sheets.list_org_sheets()
sheets = action.result

Fetch each sheet (using Assume-User):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}?include=discussions,attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Assume-User: OWNER_EMAIL"
// [todo]
// [todo]
// [todo]
dl_path = 'backup'
for org_sheet in sheets:
    smartsheet.assume_user(org_sheet.owner)
    sheet = smartsheet.Sheets.get_sheet(
        org_sheet.id,
        include='discussions,attachments'
    )

Fetch each attachment:

curl -0 URL_TO_ATTACHMENT
// [todo]
// [todo]
// [todo]
for attachment in sheet.attachments:
    attachment_obj = smartsheet.Attachments.get_attachment(sheet.id, attachment.id)
    result = smartsheet.Attachments.download_attachment(attachment_obj, dl_path)
    if result.message == 'SUCCESS':
        print(result.filename + ' downloaded')

To backup all of the org data, follow these steps:

  1. Get a list of all sheets in your organization.
  2. For each sheet in the list, fetch the sheet (optionally including a list of discussions and attachments) by assuming the identity of the owner of the sheet. (The value of the Assume-User header must be the URI-encoded email address of the sheet owner.)
  3. To backup all files attached to each sheet, fetch them one at a time, using your favorite download method. See Get Attachment for more information.

You can use the sheet version number to enable incremental backups. Fetch the sheet version number and compare it to the last backed up version number (you will need to store the sheet ID and the last backup up version number) - if they are the same, no need to include the sheet in your incremental backup run.

Backup Script

mkdir backup
curl https://api.smartsheet.com/2.0/users/sheets \
-H "Authorization: Bearer ACCESS_TOKEN"
...
// [todo]
// [todo]
// [todo]
import smartsheet
import os

os.mkdir('backup')
os.chdir('backup')

smartsheet = smartsheet.Smartsheet()

action = smartsheet.Sheets.list_org_sheets()
sheets = action.result

for org_sheet in sheets:
    os.mkdir(str(org_sheet.id))
    dl_path = os.path.realpath(str(org_sheet.id))

    smartsheet.assume_user(org_sheet.owner)
    sheet = smartsheet.Sheets.get_sheet(
        org_sheet.id,
        include='discussions,attachments'
    )

    # download all attachments
    for attachment in sheet.attachments:
        attachment_obj = smartsheet.Attachments.get_attachment(sheet.id, attachment.id)
        result = smartsheet.Attachments.download_attachment(attachment_obj, dl_path)
        if result.message == 'SUCCESS':
            print(result.filename + ' downloaded')

    # download sheet itself
    smartsheet.Sheets.get_sheet_as_csv(org_sheet.id, dl_path)

API Change Log

This section documents the evolution of Smartsheet API 2.0 over time. To stay informed about changes to the API, we recommend that you periodically review this list for new information, subscribe to our Developer Newsletter (using the Get Developer Updates form on the Smartsheet Developer Portal) or follow us via Twitter.

March 11, 2016

Backward-compatible updates to Smartsheet API 2.0.

  • API enhancements that enable you to attach a link to a file in OneDrive.

  • API enhancements that enable you to differentially share individual items within a workspace and to identify the scope of each Share for any shared item.

  • API enhancements that provide additional information about published sheets and reports and allow you to more tightly control who can access a published sheet or report.

  • API support for Sights.

  • Added createdAt and modifiedAt to the Share object.

For more detailed information about this release, see the release notes.

January 15, 2016

Backward-compatible updates to Smartsheet API 2.0.

  • New endpoints for adding an image to a cell within a sheet and getting URLs for images that are stored in sheet cells.

  • API enhancements that add support for enabling partial success of a (bulk) Add Row(s) or Update Row(s) operation, provide additional information for each object in List Public Templates response, and return a new user setting for sheets where Calendar View has been configured.

  • Errors: Several new error codes and a new (alternate) message for error code 4004.

  • Bug fix: Operations that contain Column objects in the response will now include tags CALENDAR_START_DATE and CALENDAR_END_DATE if the Sheet’s Calendar View has been configured, even if Gantt is disabled for the sheet.

For more detailed information about this release, see the release notes.

December 11, 2015

Backward-compatible updates to Smartsheet API 2.0.

For more detailed information about this release, see the release notes.

September 18, 2015

Backward-compatible updates to Smartsheet API 2.0.

  • New error code to indicate that the request should be retried: Smartsheet error code 4004 (HTTP Response code 500).

August 14, 2015

Backward-compatible updates to Smartsheet API 2.0.

  • New endpoints for accessing Contacts, copy/move Folder/Sheet, copy Workspace, bulk Row delete, bulk Send Rows, Send Update Request.

  • API enhancements that enable you to attach a link to a file in Egnyte, lock and unlock Rows/Columns, get more information about Sheets/Reports/Users, choose Columns to include when sending Rows via email, send a Gantt view of a Sheet via email (in PDF format), create Discussion on Row using a multipart upload, include everything when copying a Row from one sheet to another, and retrieve a permalink for a Row.

  • New access scope for retrieving Contacts.

  • Deprecations: Delete (single) Row endpoint, Send (single) Row endpoint, fromId attribute and include parameter on the Create Sheet/Folder/Workspace endpoints.

  • Bug fixes: Add Column(s) operation now returns correct Ids for new columns; Revoke Token operation no longer returns error code 1004 “not authorized”.

For more detailed information about this release, see the release notes.

July 11, 2015

Initial release of Smartsheet API 2.0. For detailed information about API 2.0 features and guidance for migrating from API 1.1 to API 2.0, see the release notes.

API Reference

Attachments

Attachments can exist on a Comment (i.e., within a Discussion), on a Row, or on a Sheet.

Objects

Attachment Object

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

Posting an Attachment

Like the Smartsheet web application, 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 (i.e., 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 (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.

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 will separate 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 will specify 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 will 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 ACCESS_TOKEN
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), and Smartsheet will make 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 ACCESS_TOKEN
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):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"
// n/a
// Attach file to comment.
smartsheet.SheetResources.CommentResources.AttachmentResources.AttachFile(sheetId, commentId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to comment.
smartsheet.sheetResources().commentResources().attachmentResources().attachFile(sheetId, commentId, file, "application/msword");
# Attach file to comment.
smartsheet.Attachments.attach_file_to_comment(
    sheetId,
    commentId,
    ('ProgressReport.docx', 
     open('/path/to/ProgressReport.docx', 'rb'), 
     'application/msword')
)

Example Request (simple):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx
// Set options.
var options = {
    contentType: CONTENT_TYPE,
    fileName: NAME_OF_FILE,
    fileSize: SIZE_OF_FILE,
    body: ATTACHMENT_DATA,
    sheetId: 2252168947361668,
    commentId: 4293147074291588
};

// Attach file to comment.
smartsheet.sheets.addCommentAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// Attach file to comment.
smartsheet.SheetResources.CommentResources.AttachmentResources.AttachFile(sheetId, commentId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to comment.
smartsheet.sheetResources().commentResources().attachmentResources().attachFile(sheetId, commentId, file, "application/msword");
# Attach file to comment.
smartsheet.Attachments.attach_file_to_comment(
    sheetId,
    commentId,
    ('ProgressReport.docx', 
     open('/path/to/ProgressReport.docx', 'rb'), 
     'application/msword')
)

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "FILE",
        "createdAt": "2013-02-28T21:04:56-08:00",
        "id": 4583173393803140,
        "mimeType": "application/msword",
        "name": "ProgressReport.docx"
    },
    "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 Posting an Attachment.

This operation will always create 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 Posting an Attachment for details.
Request Body Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Returns Result object containing an Attachment object for the newly created attachment

Attach File to Row

Example Request (multipart):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"
// n/a
// Attach file to row.
smartsheet.SheetResources.RowResources.AttachmentResources.AttachFile(sheetId, rowId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to row.
smartsheet.sheetResources().rowResources().attachmentResources().attachFile(sheetId, rowId, file, "application/msword");
# Attach file to row.
smartsheet.Attachments.attach_file_to_row(
    sheetId,
    rowId,
    ('ProgressReport.docx', 
     open('/path/to/ProgressReport.docx', 'rb'), 
     'application/msword')
)

Example Request (simple):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx
// Set options.
var options = {
    contentType: CONTENT_TYPE,
    fileName: NAME_OF_FILE,
    fileSize: SIZE_OF_FILE,
    body: ATTACHMENT_DATA,
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Attach file to row.
smartsheet.sheets.addRowAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// Attach file to row.
smartsheet.SheetResources.RowResources.AttachmentResources.AttachFile(sheetId, rowId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to row.
smartsheet.sheetResources().rowResources().attachmentResources().attachFile(sheetId, rowId, file, "application/msword");
# Attach file to row.
smartsheet.Attachments.attach_file_to_row(
    sheetId,
    rowId,
    ('ProgressReport.docx', 
     open('/path/to/ProgressReport.docx', 'rb'), 
     'application/msword')
)

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "FILE",
        "createdAt": "2013-02-28T21:04:56-08:00",
        "id": 4583173393803140,
        "mimeType": "application/msword",
        "name": "ProgressReport.docx"
    },
    "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 Posting an Attachment.

This operation will always create 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 Posting an Attachment for details.
Request Body Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Returns Result object containing an Attachment object for the newly created attachment

Attach File to Sheet

Example Request (multipart):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"
// n/a
// Attach file to sheet.
smartsheet.SheetResources.AttachmentResources.AttachFile(sheetId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to sheet.
smartsheet.sheetResources().attachmentResources().attachFile(sheetId, file, "application/msword");
# Attach file to sheet.
smartsheet.Attachments.attach_file_to_sheet(
    sheetId,
    ('ProgressReport.docx', 
     open('/path/to/ProgressReport.docx', 'rb'), 
     'application/msword')
)

Example Request (simple):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx
// Set options.
var options = {
    contentType: CONTENT_TYPE,
    fileName: NAME_OF_FILE,
    fileSize: SIZE_OF_FILE,
    body: ATTACHMENT_DATA,
    sheetId: 2252168947361668
};

// Attach file to sheet.
smartsheet.sheets.addAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// Attach file to sheet.
smartsheet.SheetResources.AttachmentResources.AttachFile(sheetId, filePath, "application/msword");
// Specify file to be attached.
File file = new File(filePath);

// Attach file to sheet.
smartsheet.sheetResources().attachmentResources().attachFile(sheetId, file, "application/msword");
# Attach file to sheet.
smartsheet.Attachments.attach_file_to_sheet(
    sheetId,
    ('ProgressReport.docx', 
     open('/path/to/ProgressReport.docx', 'rb'), 
     'application/msword')
)

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "FILE",
        "createdAt": "2013-02-28T21:04:56-08:00",
        "id": 4583173393803140,
        "mimeType": "application/msword",
        "name": "ProgressReport.docx"
    },
    "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 Posting an Attachment.

This operation will always create 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 Posting an Attachment for details.
Request Body Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Returns Result object containing an Attachment object for the newly created attachment

Attach URL to Comment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'
// Specify URL attachment.
var attachment = {
    "name": "Search Engine",
    "attachmentType": "LINK",
    "url": "http://www.google.com"
};

// Set options.
var options = {
    body: attachment,
    sheetId: 2252168947361668,
    commentId: 4445024629876612
};

// Attach URL to comment.
smartsheet.sheets.addCommentAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder("http://www.google.com", AttachmentType.LINK).SetName("Search Engine").SetDescription("A popular search engine").Build();

// Attach URL to comment.
smartsheet.SheetResources.CommentResources.AttachmentResources.AttachUrl(sheetId, commentId, attachment);
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder().setUrl("http://www.google.com").setAttachmentType(AttachmentType.LINK).setName("Search Engine").setDescription("A popular search engine").build();

// Attach URL to comment.
smartsheet.sheetResources().commentResources().attachmentResources().attachUrl(sheetId, commentId, attachment);
# Create URL attachment.
url = smartsheet.models.Attachment({
    'name': 'Search Engine',
    'attachment_type': 'LINK',
    'url': 'http://www.google.com'
})

# Attach URL to comment.
smartsheet.Attachments.attach_url_to_comment(sheetId, commentId, url)

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

  • a normal URL (attachmentType “LINK”)
  • a Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • a Box.com URL (attachmentType “BOX_COM”)
  • a Dropbox URL (attachmentType “DROPBOX”)
  • an Evernote URL (attachmentType “EVERNOTE”)
  • an Egnyte URL (attachmentType “EGNYTE”)
  • a OneDrive URL (attachmentType “ONEDRIVE”)

Attach URL to Row

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'
// Specify URL attachment.
var attachment = {
    "name": "Search Engine",
    "description": "A popular search engine",
    "attachmentType": "LINK",
    "url": "http://www.google.com"
};

// Set options.
var options = {
    body: attachment,
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Attach URL to row.
smartsheet.sheets.addRowAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder("http://www.google.com", AttachmentType.LINK).SetName("Search Engine").SetDescription("A popular search engine").Build();

// Attach URL to row.
smartsheet.SheetResources.RowResources.AttachmentResources.AttachUrl(sheetId, rowId, attachment);
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder().setUrl("http://www.google.com").setAttachmentType(AttachmentType.LINK).setName("Search Engine").setDescription("A popular search engine").build();

// Attach URL to row.
smartsheet.sheetResources().rowResources().attachmentResources().attachUrl(sheetId, rowId, attachment);
# Create URL attachment.
url = smartsheet.models.Attachment({
    'name': 'Search Engine',
    'description': 'A popular search engine.'
    'attachment_type': 'LINK',
    'url': 'http://www.google.com'
})

# Attach URL to row.
smartsheet.Attachments.attach_url_to_row(sheetId, rowId, url)

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

  • a normal URL (attachmentType “LINK”)
  • a Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • a Box.com URL (attachmentType “BOX_COM”)
  • a Dropbox URL (attachmentType “DROPBOX”)
  • an Evernote URL (attachmentType “EVERNOTE”)
  • an Egnyte URL (attachmentType “EGNYTE”)
  • a OneDrive URL (attachmentType “ONEDRIVE”)

Attach URL to Sheet

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name":"Search Engine", "description": "A popular search engine", "attachmentType":"LINK", "url":"http://www.google.com"}'
// Specify URL attachment.
var attachment = {
    "name": "Search Engine",
    "description": "A popular search engine",
    "attachmentType": "LINK",
    "url": "http://www.google.com"
};

// Set options.
var options = {
    body: attachment,
    sheetId: 2252168947361668
};

// Attach URL to sheet.
smartsheet.sheets.addAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder("http://www.google.com", AttachmentType.LINK).SetName("Search Engine").SetDescription("A popular search engine").Build();

// Attach URL to sheet.
smartsheet.SheetResources.AttachmentResources.AttachUrl(sheetId, attachment);
// Create attachment.
Attachment attachment = new Attachment.CreateAttachmentBuilder().setUrl("http://www.google.com").setAttachmentType(AttachmentType.LINK).setName("Search Engine").setDescription("A popular search engine").build();

// Attach URL to sheet.
smartsheet.sheetResources().attachmentResources().attachUrl(sheetId, attachment);
# Create URL attachment.
url = smartsheet.models.Attachment({
    'name': 'Search Engine',
    'description': 'A popular search engine.',
    'attachment_type': 'LINK',
    'url': 'http://www.google.com'
})

# Attach URL to sheet.
smartsheet.Attachments.attach_url_to_sheet(sheetId, url)

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

  • a normal URL (attachmentType “LINK”)
  • a Google Drive URL (attachmentType “GOOGLE_DRIVE”)
  • a Box.com URL (attachmentType “BOX_COM”)
  • a Dropbox URL (attachmentType “DROPBOX”)
  • an Evernote URL (attachmentType “EVERNOTE”)
  • an Egnyte URL (attachmentType “EGNYTE”)
  • a OneDrive URL (attachmentType “ONEDRIVE”)

Delete Attachment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    sheetId: 2252168947361668,
    attachmentId: 7169782752536452,
};

// Delete attachment.
smartsheet.sheets.deleteAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete attachment.
smartsheet.SheetResources.AttachmentResources.DeleteAttachment(sheetId, attachmentId);
// Delete attachment.
smartsheet.sheetResources().attachmentResources().deleteAttachment(sheetId, sheetAttachmentId);
# Delete attachment.
smartsheet.Attachments.delete_attachment(sheetId, attachmentId)

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 ACCESS_TOKEN
Returns Result object

Get Attachment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    attachmentId: 4583173393803140
};

// Get attachment.
smartsheet.sheets.getAttachment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get attachment.
smartsheet.SheetResources.AttachmentResources.GetAttachment(sheetId, attachmentId);
// Get attachment.
smartsheet.sheetResources().attachmentResources().getAttachment(sheetId, attachmentId);
# Get attachment.
attachment = smartsheet.Attachments.get_attachment(sheetId, attachmentId)

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 ACCESS_TOKEN
Returns Attachment object. For File attachments, this will include a temporary URL for downloading the file.

Currently, the temporary URL is set to expire in 120000 milliseconds, or 2 minutes.

Get All Attachments

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668
};

// Get all attachments.
smartsheet.sheets.listAttachments(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get all attachments (omit pagination parameters).
smartsheet.SheetResources.AttachmentResources.ListAttachments(sheetId, null);

// Get all attachments (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.AttachmentResources.ListAttachments(sheetId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all attachments with pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().listAttachments(sheetId, parameters);

// Get all attachments without pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().listAttachments(sheetId, null);
# Get all attachments.
action = smartsheet.Attachments.list_all_attachments(sheetId, include_all=True)
attachments = action.data

# Get a paginated list of attachments.
action = smartsheet.Attachments.list_all_attachments(
    sheetId, 
    page_size=10, 
    page=1)
pages = action.total_pages
attachments = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "name": "att3.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "SHEET",
            "parentId" : 341847495283
        },
        {
            "name": "att4.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 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 ACCESS_TOKEN
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

Get Discussion Attachments

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    discussionId: 3962273862576004
};

// Get discussion attachments.
smartsheet.sheets.listDiscussionAttachments(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get discussion attachments (omit pagination parameters).
smartsheet.SheetResources.DiscussionResources.AttachmentResources.ListAttachments(sheetId, discussionId, null);

// Get discussion attachments (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.DiscussionResources.AttachmentResources.ListAttachments(sheetId, discussionId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all discussion attachments with pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().discussionResources().attachmentResources().getAttachments(sheetId, discussionId, parameters);

// Get all discussion attachments without pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().discussionResources().attachmentResources().getAttachments(sheetId, discussionId, null);
# Get discussion attachments.
action = smartsheet.Attachments.list_discussion_attachments(
    sheetId, 
    discussionId, 
    include_all=True)
attachments = action.data

# Get paginated list of discussion attachments.
action = smartsheet.Attachments.list_discussion_attachments(
    sheetId, 
    discussionId, 
    page_size=10, 
    page=1)
pages = action.total_pages
attachments = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "name": "att3.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "COMMENT",
            "parentId" : 341847495283
        },
        {
            "name": "att4.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 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 ACCESS_TOKEN
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

Get Row Attachments

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Get row attachments.
smartsheet.sheets.getRowAttachments(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get row attachments (omit pagination parameters).
smartsheet.SheetResources.RowResources.AttachmentResources.ListAttachments(sheetId, rowId, null);

// Get row attachments (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.RowResources.AttachmentResources.ListAttachments(sheetId, rowId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all row attachments with pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().rowResources().attachmentResources().getAttachments(sheetId, rowId, parameters);

// Get all row attachments without pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().rowResources().attachmentResources().getAttachments(sheetId, rowId, null);
# Get row attachments.
action = smartsheet.Attachments.list_row_attachments(
    sheetId, 
    rowId, 
    include_all=True)
attachments = action.data

# Get paginated list of row attachments.
action = smartsheet.Attachments.list_row_attachments(
    sheetId, 
    rowId, 
    page_size=10, 
    page=1)
pages = action.total_pages
attachments = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "name": "att3.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 4583173393803140,
            "parentType" : "ROW",
            "parentId" : 341847495283
        },
        {
            "name": "att4.png",
            "attachmentType": "FILE",
            "mimeType": "image/png",
            "id": 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 ACCESS_TOKEN
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):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X POST \
-F "file=@ProgressReport.docx;type=application/msword"
// n/a
// Attach new version of file.
smartsheet.SheetResources.AttachmentResources.VersioningResources.AttachNewVersion(sheetId, attachmentId, filePath, "application/msword");
// Specify the new file to be attached.
File file = new File(filePath);

// Attach new version of the file.
smartsheet.sheetResources().attachmentResources().versioningResources().attachNewVersion(sheetId, attachmentId, file, "application/msword");
# Attach new version of file.
action = smartsheet.Attachments.attach_new_version(
    sheetId,
    attachmentId,
    ('ProgressReport.docx',
     open('/path/to/ProgressReport.docx', 'rb'),
     'application/msword')
)
# action.message == 'SUCCESS'
# action.result is an Attachment object

Example Request (simple):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/msword" \
-H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @ProgressReport.docx
// Set options.
var options = {
    contentType: CONTENT_TYPE,
    fileName: NAME_OF_FILE,
    fileSize: SIZE_OF_FILE,
    body: ATTACHMENT_DATA,
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Attach new version of the file.
smartsheet.sheets.attachNewVersion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// Attach new version of file.
smartsheet.SheetResources.AttachmentResources.VersioningResources.AttachNewVersion(sheetId, attachmentId, filePath, "application/msword");
// Specify the new file to be attached.
File file = new File(filePath);

// Attach new version of the file.
smartsheet.sheetResources().attachmentResources().versioningResources().attachNewVersion(sheetId, attachmentId, file, "application/msword");
# Attach new version of file.
action = smartsheet.Attachments.attach_new_version(
    sheetId,
    attachmentId,
    ('ProgressReport.docx',
     open('/path/to/ProgressReport.docx', 'rb'),
     'application/msword')
)
# action.message == 'SUCCESS'
# action.result is an Attachment object

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "attachmentType": "FILE",
        "createdAt": "2013-02-28T21:04:56-08:00",
        "id": 4583173393803140,
        "mimeType": "application/msword",
        "name": "ProgressReport.docx"
    },
    "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 Posting an Attachment.

Access Scope WRITE_SHEETS
Headers Required headers vary depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Request Body Request body varies depending on the type of upload being performed (simple upload or multipart upload). See Posting an Attachment for details.
Returns Result object containing an Attachment object for the newly created attachment

Delete All Versions

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    sheetId: 2252168947361668,
    attachmentId: 5510069950408580
};

// Delete all versions of the attachment.
smartsheet.sheets.deleteAllAttachmentVersions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete all versions of the attachment. 
smartsheet.SheetResources.AttachmentResources.VersioningResources.DeleteAllVersions(sheetId, attachmentId);
// Delete all versions of the attachment.
smartsheet.sheetResources().attachmentResources().versioningResources().deleteAllVersions(sheetId, attachmentId);
# Delete all versions of the attachment.
smartsheet.Attachments.delete_attachment_versions(sheetId, attachmentId)

Example Response:

{
    "message": "SUCCESS",
    "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 will effectively delete the attachment from the object that it’s attached to.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

List All Versions

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    attachmentId: 5510069950408580
};

// List all versions of the attachment.
smartsheet.sheets.listAttachmentVersions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List all versions of the attachment (omit pagination parameters).
smartsheet.SheetResources.AttachmentResources.VersioningResources.ListVersions(sheetId, attachmentId, null);

// List all versions of the attachment (specify 'includeAll' parameter with value of "true").
smartsheet.SheetResources.AttachmentResources.VersioningResources.ListVersions(sheetId, attachmentId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List all attachment versions with pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().versioningResources().listAllVersions(sheetId, attachmentId, parameters);

// List all attachment versions without pagination.
PagedResult<Attachment> attachments = smartsheet.sheetResources().attachmentResources().versioningResources().listAllVersions(sheetId, attachmentId, null);
# List all attachment versions.
action = smartsheet.Attachments.list_attachment_versions(
    sheetId, 
    attachmentId, 
    include_all=True)
versions = action.data

# Get paginated list of attachments.
action = smartsheet.Attachments.list_attachment_versions(
    sheetId, 
    attachmentId, 
    page_size=5, 
    page=1)
pages = action.total_pages
versions = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": 4583173393803140,
            "name": "at3.png",
            "attachmentType": "file",
            "mimeType": "image/png",
            "createdAt": "2014-03-28T18:13:20-07:00"
        },
        {
            "id": 642523719853956,
            "name": "at3.png",
            "attachmentType": "file",
            "mimeType": "image/png",
            "createdAt": "2014-03-27T18:11:11-07:00"
        }
    ]
}

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

Gets a list of all versions of the given Attachment ID, in order from newest to oldest.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
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

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 Values.
displayValue string Visual representation of cell contents, as presented to the user in the UI. See Cell Values.
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
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.
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 will never be 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 will contain the URL value.

When the hyperlink is a Sheet/Report/Sight link (i.e. sheetId or reportId or sightId is non-null), this property will contain the permalink to the Sheet or 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 ACCESS_TOKEN" \
-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 will be 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 application 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 (e.g. days, hours, minutes, etc.) will always be 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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history?include=columnType \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    rowId: 4293147074291588,
    columnId: 642523719853956
};

// Get cell history.
smartsheet.sheets.getCellHistory(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get cell history (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(sheetId, rowId, columnId, null, null);

// Get cell history (specify 'include' parameter with value of "columnType" and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(sheetId, rowId, columnId, new CellInclusion[] { CellInclusion.COLUMN_TYPE }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get cell history with pagination.
PagedResult<CellHistory> cellHistory = smartsheet.sheetResources().rowResources().cellResources().getCellHistory(sheetId, rowId, columnId, parameters);

// Get cell history without pagination.
PagedResult<CellHistory> cellHistory = smartsheet.sheetResources().rowResources().cellResources().getCellHistory(sheetId, rowId, columnId, null);
# Get all cell history.
action = smartsheet.Cells.get_cell_history(
    sheetId,
    rowId,
    columnId,
    include_all=True)
revisions = action.data

# Get paginated list of cell history.
action = smartsheet.Cells.get_cell_history(
    sheetId,
    rowId,
    columnId,
    page_size=5,
    page=1)
pages = action.total_pages
revisions = action.data

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 ACCESS_TOKEN
Parameters include (optional): when specified with a value of “columnType”, response will include 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 Cell(s)

To update the Cells in a Sheet, use the Update Row(s) operation.

Images in Cells

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

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 will result 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 will be 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.

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 will be derived from the hyperlink:

  • If the hyperlink is a URL link, the cell’s value will be set to the URL itself.
  • If the hyperlink is a sheet or report or Sight link, the cell’s value will be set to the sheet or report or Sight name.

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

imageId string Image ID
width number Image width (in pixels).
In the Get Image URLs request, this (optional) attribute represents requested width; in the response, it represents actual width of the image returned. (See Get Image URLs.)
height number Image height (in pixels).
In the Get Image URLs request, this (optional) attribute represents requested height; in the response, it represents actual height of the image returned. (See Get Image URLs.)
url string Temporary URL that can be used to retrieve the image. This attribute can be present in a response but will never be specified in a request.
error Error Error object. Present in the Get Image URLs response only if an error occurred retrieving the image.

ImageUrlMap Object

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

Add Image to Cell

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages?altText=my%20image \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/jpeg" \
-H 'Content-Disposition: attachment; filename="picture.jpg"' \
-H "Content-Length: FILE_SIZE" \
-X POST \
--data-binary @picture.jpg
// [todo]
// [todo]
// [todo]
# [todo]

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
Request Body Binary content for the file
Returns Result object

Get Image URLs

Example Request:

curl https://api.smartsheet.com/2.0/imageurls \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application\json" \
-X POST \
-d '[{"imageId": "e1znCxhuZo_soEJtUmmX_A","height":40,"width": 20},{"imageId": "g2jdKdfhQa_abKJmPnhC_B","height":100,"width": 50}]'
// [todo]
// [todo]
// [todo]
# [todo]

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 ACCESS_TOKEN
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 will be 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 (i.e., one or the other – not both), the image will be 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, then the returned image size matches the requested size.
  • If the requested image size is larger than the actual image size, then the returned image size will match 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 Row(s) 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 Row(s) 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.

Cells

For details about working with the cells within a Sheet, see Cells.

Columns

A Column is a component of a Sheet or Report.

Objects

Column Object

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
hidden boolean Flag indicating whether the column is hidden
symbol string When applicable for CHECKBOX column type:
  • STAR
  • FLAG
When applicable for PICKLIST column type:
  • HARVEY_BALLS
  • PRIORITY
  • RYG
  • PRIORITY_HML
  • DECISION_SYMBOLS
  • DECISION_SHAPES
  • VCR
  • RYGB
  • RYGG
  • WEATHER
  • PROGRESS
  • ARROWS_3_WAY
  • ARROWS_4_WAY
  • ARROWS_5_WAY
  • DIRECTIONS_3_WAY
  • DIRECTIONS_4_WAY
  • SKI
  • SIGNAL
  • STAR_RATING
  • HEARTS
  • MONEY
  • EFFORT
  • PAIN
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 will be 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
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.

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 will include 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 will match 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 Column(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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", "index":4}, {"title": "New Picklist Column 2", "type": "PICKLIST", "options": ["1", "2", "3"], "index": 4}]'
// Specify new columns.
var column = [
    {
        "title": "New Picklist Column 1",
        "type": "PICKLIST",
        "options": [
            "First",
            "Second",
            "Third"
        ],
        "index": 4
    },
    {
        "title": "New Date Column",
        "type": "DATE",
        "index": 5
    },
    {
        "title": "New Picklist Column 2",
        "type": "PICKLIST",
        "options":[
            "1",
            "2",
            "3"
        ],
        "index": 6
    }
];

// Set options.
var options = {
    body: column,
    sheetId: 2252168947361668
};

// Add columns to the sheet.
smartsheet.sheets.addColumn(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create a column.
Column columnA = new Column.AddColumnBuilder("New Picklist Column 1", 4, ColumnType.PICKLIST).SetOptions(new string[] { "First", "Second", "Third" }).Build();

// Create another column.
Column columnB = new Column.AddColumnBuilder("New Date Column", 4, ColumnType.DATE).Build();

// Create a third column.
Column columnC = new Column.AddColumnBuilder("New Picklist Column 2", 4, ColumnType.PICKLIST).SetOptions(new string[] { "1", "2", "3" }).Build();

// Add columns to the sheet.
smartsheet.SheetResources.ColumnResources.AddColumns(sheetId, new Column[] { columnA, columnB, columnC });
// Create columns.
Column column1 = new Column.AddColumnToSheetBuilder().setTitle("New Picklist Column 1").setType(ColumnType.PICKLIST).setIndex(4).setOptions(Arrays.asList("First", "Second", "Third")).build();

Column column2 = new Column.AddColumnToSheetBuilder().setTitle("New Date Column").setType(ColumnType.DATE).setIndex(4).build();

Column column3 = new Column.AddColumnToSheetBuilder().setTitle("New Picklist Column 2").setType(ColumnType.PICKLIST).setIndex(4).setOptions(Arrays.asList("1", "2", "3")).build();

// Add columns to the sheet.
smartsheet.sheetResources().columnResources().addColumns(sheetId(), Arrays.asList(column1, column2, column3));
# Create the columns.
column1 = smartsheet.models.Column({
    'title': 'New Picklist Column 1',
    'type': 'PICKLIST',
    'options': [
        'First',
        'Second',
        'Third'
    ],
    'index': 4
})

column2 = smartsheet.models.Column({
    'title': 'New Date Column',
    'type': 'DATE',
    'index': 4
})

column3 = smartsheet.models.Column({
    'title': 'New Picklist Column 2',
    'type': 'PICKLIST',
    'options': ['1', '2', '3'],
    'index': 4
})

# Add columns to the sheet.
smartsheet.Sheets.add_columns(sheetId, [column1, column2, column3])

Example Response:

{
    "resultCode": 0,
    "result": [
        {
            "id": 9007194052434043,
            "index": 4,
            "title": "New Picklist Column 1",
            "type": "PICKLIST",
            "options": [
                "First",
                "Second",
                "Third"
            ],
            "width": 150
        },
        {
            "id": 4503594425063547,
            "index": 4,
            "title": "New Date Column",
            "type": "DATE",
            "width": 150
        },
        {
            "id": 6755394238748795,
            "index": 4,
            "title": "New Picklist Column 2",
            "type": "PICKLIST",
            "options": [
                "1",
                "2",
                "3"
            ],
            "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 ACCESS_TOKEN
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)
  • width (optional)
  • locked (optional)
Returns Result object containing the the newly created column(s) – either a single Column object or an array of Column objects, corresponding to what was specified in the request.

Delete Column

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    sheetId: 2252168947361668,
    columnId: 7881817631025028
};

// Delete column.
smartsheet.sheets.deleteColumn(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete column.
smartsheet.SheetResources.ColumnResources.DeleteColumn(sheetId, columnId);
// Delete column.
smartsheet.sheetResources().columnResources().deleteColumn(sheetId, columnId);
# Delete column.
smartsheet.Sheets.delete_column(sheetId, columnId)

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 ACCESS_TOKEN
Returns Result object

Get Column

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    columnId: 7960873114331012
};

// Get column.
smartsheet.sheets.getColumns(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get column (omit 'include' parameter).
smartsheet.SheetResources.ColumnResources.GetColumn(sheetId, columnId, null);

// Get column (specify 'include' parameter with value of "filters").
smartsheet.SheetResources.ColumnResources.GetColumn(sheetId, columnId, new ColumnInclusion[] { ColumnInclusion.FILTERS });
// Get column (omit 'include' parameter).
smartsheet.sheetResources().columnResources().getColumn(sheetId, columnId, null);

// Get column (specify 'include' parameter with value of "filters").
smartsheet.sheetResources().columnResources().getColumn(sheetId, columnId, EnumSet.of(ColumnInclusion.FILTERS));
# Get column.
column = smartsheet.Sheets.get_column(sheetId, columnId)

Example Response:

{
    "id": 7960873114331012,
    "index": 2,
    "symbol": "STAR",
    "title": "Favorite",
    "type": "CHECKBOX"
}

GET /sheets/{sheetId}/columns/{columnId}

Gets the Column specified in the URL.

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

Get All Columns

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668
};

// Get all columns.
smartsheet.sheets.getColumns(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get all columns (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.ColumnResources.ListColumns(sheetId, null, null);

// Get all columns (specify 'include' parameter with value of "filters" and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.ColumnResources.ListColumns(sheetId, new ColumnInclusion[] { ColumnInclusion.FILTERS }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'.
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all columns (specify 'include' parameter with value of "filters" and 'includeAll' parameter with value of "true").
smartsheet.sheetResources().columnResources().listColumns(sheetId, EnumSet.of(ColumnInclusion.FILTERS), parameters);

// Get all columns (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().columnResources().listColumns(sheetId, null, null);
# Get all columns.
action = smartsheet.Sheets.get_columns(sheetId, include_all=True)
columns = action.data

# Get paginated list of columns (100 columns per page).
action = smartsheet.Sheets.get_columns(sheetId)
pages = action.total_pages
columns = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 3,
    "data": [
        {
            "id": 7960873114331012,
            "index": 0,
            "symbol": "STAR",
            "title": "Favorite",
            "type": "CHECKBOX"
        },
        {
            "id": 642523719853956,
            "index": 1,
            "primary": true,
            "title": "Primary Column",
            "type": "TEXT_NUMBER"
        },
        {
            "id": 5146123347224452,
            "index": 2,
            "title": "Status",
            "type": "PICKLIST"
        }
    ]
}

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 ACCESS_TOKEN
Parameters include (optional): when specified with a value of “filters”, response will include 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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X PUT \
-d '{"title":"First Column","index":0, "type" : "PICKLIST", "options" :["One","Two"]}'
// Specify column properties.
var column = {
    "index": 0,
    "title": "First Column",
    "type": "PICKLIST",
    "options": ["One", "Two"]
};

// Set options.
var options = {
    body: column,
    sheetId: 2252168947361668,
    columnId: 5005385858869124
};

// Update column.
smartsheet.sheets.updateColumn(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify column properties.
Column column = new Column.UpdateColumnBuilder(columnId, "First Column", 0).SetType(ColumnType.PICKLIST).SetOptions(new string[] { "One", "Two" }).Build();

// Update column.
smartsheet.SheetResources.ColumnResources.UpdateColumn(sheetId, column);
// Specify column properties.
Column column = new Column.UpdateColumnBuilder().setColumnId(columnId).setTitle("First Column").setIndex(0).setType(ColumnType.PICKLIST).setOptions(Arrays.asList("One", "Two")).build();

// Update column.
smartsheet.sheetResources().columnResources().updateColumn(sheetId, column);
# Specify column properties.
altered_column = smartsheet.models.Column({
    'title': 'First Column',
    'type': 'PICKLIST',
    'options': ["One", "Two"],
    'index': 0
})

# Update column.
action = smartsheet.Sheets.update_column(sheetId, columnId, altered_column)
# action.result is an instance of smartsheet.models.Column

Example Response:

{
    "message": "SUCCESS",
    "result": {
        "id": 5005385858869124,
        "index": 0,
        "options" : ["One", "Two"],
        "title": "First Column",
        "type": "PICKLIST"
    },
    "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 will be converted to the new column type.
  • Type is optional when moving or renaming, but required when changing type or dropdown values.

    Access Scope ADMIN_SHEETS
    Headers Authorization: Bearer ACCESS_TOKEN
    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)
    • width (optional)
    • format (optional)
    • locked (optional)
    Returns Result object containing the Column object that was modified

Comments

A Comment is a component of a Discussion. Each Discussion is composed of one or more Comments.

Objects

Comment Object

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

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"text":"This is a new comment."}'
// Specify comment.
var comment = { "text": "This is a new comment." };

// Set options.
var options = {
    body: comment,
    sheetId: 2252168947361668,
    discussionId: 3962273862576004
};

// Add comment to discussion.
smartsheet.sheets.addDiscussionComment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This is a new comment.").Build();

// Add comment to discussion.
smartsheet.SheetResources.DiscussionResources.CommentResources.AddComment(sheetId, discussionId, comment);
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This is a new comment.").build();

// Add comment to discussion.
smartsheet.sheetResources().discussionResources().commentResources().addComment(sheetId, discussionId, comment);
# Add comment to discussion.
action = smartsheet.Discussions.add_comment_to_discussion(
    sheetId,
    discussionId,
    smartsheet.models.Comment({
        '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 ACCESS_TOKEN" \
-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"
    }
// [todo]
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This is a new comment.").Build();

// Add comment (with attachment) to discussion.
smartsheet.SheetResources.DiscussionResources.CommentResources.AddCommentWithAttachment(sheetId, discussionId, comment, filePath, "application/octet-stream");
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This is a new comment.").build();

// Add comment (with attachment) to discussion.
File file = new File(filePath);

smartsheet.sheetResources().discussionResources().commentResources().addCommentWithAttachment(sheetId, discussionId, comment, file, "application/octet-stream");
# Create comment.
comment = smartsheet.models.Comment({
    'text': 'You might need this.'
})

# Add comment (with attachment) to discussion.
action = smartsheet.Discussions.add_comment_to_discussion_with_attachment(
    sheetId,
    discussionId,
    comment,
    ('image.png', open('/path/to/image.png', 'rb'), 'image/png')
)

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

Delete Comment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId} \
-H "Authorization: Bearer ACCESS_TOKEN"\
-X 'DELETE'
// Set options.
var options = {
    sheetId: 2252168947361668,
    commentId: 4952999001909124
};

// Delete comment.
smartsheet.sheets.deleteComment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete comment.
smartsheet.SheetResources.CommentResources.DeleteComment(sheetId, commentId);
// Delete comment.
smartsheet.sheetResources().commentResources().deleteComment(sheetId, commentId);
# Delete comment.
smartsheet.Discussions.delete_discussion_comment(sheetId, commentId)

Example Response:

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

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

Deletes the Comment specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Comment

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{id} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    commentId: 48569348493401200
};

// Get comment.
smartsheet.sheets.getComment(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get comment.
smartsheet.SheetResources.CommentResources.GetComment(sheetId, commentId);
// Get comment.
smartsheet.sheetResources().commentResources().getComment(sheetId, commentId);
# Get comment.
comment = smartsheet.Discussions.get_discussion_comment(sheetId, commendId)

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 ACCESS_TOKEN
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

id string Contact ID
name string Contact’s full name
email string Contact’s email address

Get Contact

Example Request:

curl https://api.smartsheet.com/2.0/contacts/{contactId} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Get contact.
smartsheet.ContactResources.GetContact(contactId);
// Get contact.
smartsheet.contactResources().getContact(contactId);
# Get contact.
contact = smartsheet.Contacts.get_contact(contactId)

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 ACCESS_TOKEN
Returns Contact object

List Contacts

Example Request:

curl https://api.smartsheet.com/2.0/contacts \
-H "Authorization: Bearer ACCESS_TOKEN"
// List contacts (omit pagination parameters).
smartsheet.ContactResources.ListContacts(null);

// List contacts (specify 'includeAll' parameter with value of "true").
smartsheet.ContactResources.ListContacts(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List contacts (specify 'includeAll' parameter with value of "true").
smartsheet.contactResources().listContacts(parameters);

// List contacts (omit pagination parameters).
smartsheet.contactResources().listContacts(null);
# Get all contacts.
action = smartsheet.Contacts.list_contacts(include_all=True)
contacts = action.data

# Get paginated list of contacts (100 contacts per page).
action = smartsheet.Contacts.list_contacts()
pages = action.total_pages
contacts = action.data

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 ACCESS_TOKEN
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

id number Discussion ID
title string Discussion title
comments Comment[] Array of Comment objects
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 Get All Discussions)
parentType string “SHEET” or “ROW”: present only when the direct association is not clear (see Get All 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):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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"}}'
// Specify discussion.
var discussion = {
    "title": "This is a new discussion",
    "comment": {
        "text": "This text is the body of the first comment"
    }
};

// Set options.
var options = {
    body: discussion,
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Add discussion to row.
smartsheet.sheets.createRowDiscussion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This text is the body of the first comment").Build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder("This is a new discussion", comment).Build();

// Add discussion to row.
smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussion(sheetId, rowId, discussion);
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This text is the body of the first comment").build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder().setTitle("This is a new discussion").setComment(comment).build();

// Add discussion to row.
smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(sheetId, rowId, discussion);
# Add discussion to row.
action = smartsheet.Discussions.create_discussion_on_row(
    sheetId,
    rowId,
    smartsheet.models.Discussion({
        'title': 'This is a new discussion',
        'comment': smartsheet.models.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 ACCESS_TOKEN" \
-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"
        }
    }
// [todo]
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This text is the body of the first comment").Build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder("This is a new discussion", comment).Build();

// Add discussion to row.
smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussionWithAttachment(sheetId, rowId, discussion, filePath, "application/octet-stream");
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This text is the body of the first comment").build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder().setTitle("This is a new discussion").setComment(comment).build();

// Set file path
File file = new File(filePath);

// Add discussion to row.
smartsheet.sheetResources().rowResources().discussionResources().createDiscussionWithAttachment(sheetId, rowId, discussion, file, "application/octet-stream");
# Add discussion to row.
action = smartsheet.Discussions.create_discussion_on_row_with_attachment(
    sheetId,
    rowId,
    smartsheet.models.Discussion({
        'title': 'This is a new discussion',
        'comment': smartsheet.models.Comment({
            'text': 'This text is the body of the first comment'
        })
    }),
    ('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')
)

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"
    },
    "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 ACCESS_TOKEN
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):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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"}}'
// Specify discussion.
var discussion = {
    "title": "This is a new discussion",
    "comment": {
        "text": "This text is the body of the first comment"
    }
};

// Set options.
var options = {
    body: discussion,
    sheetId: 2252168947361668
};

// Add discussion to sheet.
smartsheet.sheets.createDiscussion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This text is the body of the first comment").Build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder("This is a new discussion", comment).Build();

// Add discussion to sheet.
smartsheet.SheetResources.DiscussionResources.CreateDiscussion(sheetId, discussion);
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This text is the body of the first comment").build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder().setTitle("This is a new discussion").setComment(comment).build();

// Add discussion to sheet.
smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(sheetId, rowId, discussion);
# Add discussion to sheet.
action = smartsheet.Discussions.create_discussion_on_sheet(
    sheetId,
    smartsheet.models.Discussion({
        'title': 'This is a new discussion',
        'comment': smartsheet.models.Comment({
            'text': 'This text is the body of the first comment'
        })
    })
)

Example Request (with attachment):

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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"
        }
    }
// [todo]
// Create comment.
Comment comment = new Comment.AddCommentBuilder("This text is the body of the first comment").Build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder("This is a new discussion with an attachment", comment).Build();

// Add discussion (including comment with attachment) to sheet.
smartsheet.SheetResources.DiscussionResources.CreateDiscussionWithAttachment(sheetId, discussion, filePath, "application/octet-stream");
// Create comment.
Comment comment = new Comment.AddCommentBuilder().setText("This text is the body of the first comment").build();

// Create discussion (including the comment).
Discussion discussion = new Discussion.CreateDiscussionBuilder().setTitle("This is a new discussion").setComment(comment).build();
File file = new File(filePath);

// Add discussion (including comment with attachment) to sheet.
smartsheet.sheetResources().discussionResources().createDiscussionWithAttachment(sheetId, discussion, file, "application/octet-stream");
# Add discussion to sheet.
action = smartsheet.Discussions.create_discussion_on_sheet_with_attachment(
    sheetId,
    smartsheet.models.Discussion({
        'title': 'This is a new discussion',
        'comment': smartsheet.models.Comment({
            'text': 'This text is the body of the first comment'
        })
    }),
    ('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')
)

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"
    },
    "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 ACCESS_TOKEN
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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId} \
-H "Authorization: Bearer ACCESS_TOKEN"\
-X 'DELETE'
// Set options.
var options = {
    sheetId: 2252168947361668,
    discussionId: 991393444325252
};

// Delete discussion.
smartsheet.sheets.deleteDiscussion(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete discussion.
smartsheet.SheetResources.DiscussionResources.DeleteDiscussion(sheetId, discussionId);
// Delete discussion.
smartsheet.sheetResources().discussionResources().deleteDiscussion(sheetId, discussionId);
# Delete discussion.
action = smartsheet.Discussions.delete_discussion(sheetId, discussionId)

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 ACCESS_TOKEN
Returns Result object

Get All Discussions

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions?include=comments,attachments \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 3138415114905476
};

// Get all discussions.
smartsheet.sheets.getDiscussions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get all discussions (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.DiscussionResources.ListDiscussions(sheetId, null, null);

// Get all discussions (specify 'include' parameter with values of 'comments' and 'attachments', and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.DiscussionResources.ListDiscussions(sheetId, new DiscussionInclusion[] { DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get all discussions (specify 'include' parameter with values of 'comments' and 'attachments', and 'includeAll' parameter with value of "true").
smartsheet.sheetResources().discussionResources().listDiscussions(sheetId, parameters, EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS));

// Get all discussions (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().discussionResources().listDiscussions(sheetId, null, null);
# Get all discussions.
action = smartsheet.Discussions.get_all_discussions(sheetId, include_all=True)
discussions = action.data

# Get paginated list of discussions.
action = smartsheet.Discussions.get_all_discussions(sheetId, page_size=10, page=1)
pages = action.total_pages
discussions = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 3138415114905476,
            "title": "Lincoln",
            "comments": [
                {
                    "id": 7320407591151492,
                    "text": "16th President",
                    "createdBy": {
                        "name": "Test User",
                        "email": "tester@smartsheet.com"
                    },
                    "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"
                }
            ],
            "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 ACCESS_TOKEN
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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    discussionId: 2331373580117892
};

// Get discussion.
smartsheet.sheets.getDiscussions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get discussion.
smartsheet.SheetResources.DiscussionResources.GetDiscussion(sheetId, discussionId);
// Get discussion.
smartsheet.sheetResources().discussionResources().getDiscussion(sheetId, discussionId);
# Get discussion.
discussion = smartsheet.Discussions.get_discussion(sheetId, discussionId)
# discussion is an instance of smartsheet.models.Discussion

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

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

Gets the Discussion specified in the URL.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Discussion object

Get Row Discussions

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions?include=comments,attachments \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 2252168947361668,
    rowId: 4293147074291588
};

// Get row discussions.
smartsheet.sheets.getRowDiscussions(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get row discussions (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(sheetId, rowId, null, null);

// Get row discussions (specify 'include' parameter with values of 'comments' and 'attachments', and 'includeAll' parameter with value of "true").
smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(sheetId, rowId, new DiscussionInclusion[] { DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS }, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// Get row discussions (specify 'include' parameter with values of 'comments' and 'attachments', and 'includeAll' parameter with value of "true").
smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(sheetId, rowId, parameters, EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS));

// Get row discussions (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(sheetId, rowId, null, null);
# Get row discussions.
action = smartsheet.Discussions.get_row_discussions(sheetId, rowId, include_all=True)
discussions = action.data

# Get paginated list of row discussions.
action = smartsheet.Discussions.get_row_discussions(sheetId, rowId, page_size=10)
pages = action.total_pages # starts on page 1 by default
discussions = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 3138415114905476,
            "title": "Lincoln",
            "comments": [
                {
                    "id": 7320407591151492,
                    "text": "16th President",
                    "createdBy": {
                        "name": "Test User",
                        "email": "tester@smartsheet.com"
                    },
                    "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"
                }
            ],
            "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 ACCESS_TOKEN
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

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 Favorite(s)

Example Request:

curl https://api.smartsheet.com/2.0/favorites \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"type": "sheet", "objectId": 8400677765441412}]'
// Specify favorite(s).
var favorites = [
    {
        "type": "sheet",
        "objectId": 8400677765441412
    }
];

// Set options.
var options = {
    body: favorites
};

// Add item(s) to favorites.
smartsheet.favorites.addItemsToFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify favorite(s).
Favorite[] favorites = new Favorite[] { new Favorite.AddFavoriteBuilder(ObjectType.SHEET, objectId).Build() };

// Add item(s) to favorites.
smartsheet.FavoriteResources.AddFavorites(favorites);
// Specify favorite(s).
List<Favorite> favorites = new Favorite.AddFavoriteBuilder().addFavorite(sheetId, FavoriteType.SHEET).build();

// Add item(s) to favorites.
smartsheet.favoriteResources().addFavorites(favorites);
# Add sheet to Favorites.
action = smartsheet.Favorites.add_favorites([
    smartsheet.models.Favorite({
        'type': 'sheet',
        'object_id': 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 will be returned. If called with an array of Favorite objects, any objects specified in the array that are already marked as favorites will be ignored and omitted from the response.

Access Scope ADMIN_WORKSPACES
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Favorite object or an array of Favorite objects, with the following attributes:
  • type
  • objectId
Returns Result object containing object(s) 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:

curl https://api.smartsheet.com/2.0/favorites \
-H "Authorization: Bearer ACCESS_TOKEN"
// List favorites.
smartsheet.favorites.listFavorites()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List favorites (omit pagination parameters).
smartsheet.FavoriteResources.ListFavorites(null);

// List favorites (specify 'includeAll' parameter with value of "true").
smartsheet.FavoriteResources.ListFavorites(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List favorites (specify 'includeAll' parameter with value of "true").
smartsheet.favoriteResources().listFavorites(parameters);

// List favorites (omit pagination parameters).
smartsheet.favoriteResources().listFavorites(null);
# Get all favorites.
action = smartsheet.Favorites.list_favorites(include_all=True)
favs = action.data

# Get paginated list of favorites.
action = smartsheet.Favorites.list_favorites(page_size=10, page=1)
pages = action.total_pages
favs = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "type": "sheet",
            "objectId": 5897312590423940
        },
        {
            "type": "folder",
            "objectId": 1493728255862660
        }
    ]
}

GET /favorites

Gets a list of all of the user’s Favorite items.

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
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 Sight

Example Request:

curl https://api.smartsheet.com/2.0/favorites/sights/{sightId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// [todo]
// [todo]
// [todo]
# [todo]

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 ACCESS_TOKEN
Returns Result object

Remove Favorite Folder

Example Request:

curl https://api.smartsheet.com/2.0/favorites/folder/{folderId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove folder from list of favorites.
smartsheet.favorites.removeFolderFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove folder from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.FOLDER, new long[] { folderId });
// Remove folder from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.FOLDER, new HashSet(Arrays.asList(folderId)));
# Remove folder from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'folder', 
    folderId
)

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 ACCESS_TOKEN
Returns Result object

Remove Favorite Report

Example Request:

curl https://api.smartsheet.com/2.0/favorites/report/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove report from list of favorites.
smartsheet.favorites.removeReportFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove report from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.REPORT, new long[] { reportId });
// Remove report from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.REPORT, new HashSet(Arrays.asList(reportId)));
# Remove report from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'report', 
    reportId
)

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 ACCESS_TOKEN
Returns Result object

Remove Favorite Sheet

Example Request:

curl https://api.smartsheet.com/2.0/favorites/sheet/{sheetId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove sheet from list of favorites.
smartsheet.favorites.removeSheetFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    }); 
// Remove sheet from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.SHEET, new long[] { sheetId });
// Remove sheet from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.SHEET, new HashSet(Arrays.asList(sheetId)));
# Remove sheet from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'sheet', 
    sheetId
)

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 ACCESS_TOKEN
Returns Result object

Remove Favorite Template

Example Request:

curl https://api.smartsheet.com/2.0/favorites/template/{templateId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove template from list of favorites.
smartsheet.favorites.removeTemplateFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove template from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.TEMPLATE, new long[] { templateId });
// Remove template from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.TEMPLATE, new HashSet(Arrays.asList(templateId)));
# Remove template from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'template', 
    templateId
)

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 ACCESS_TOKEN
Returns Result object

Remove Favorite Workspace

Example Request:

curl https://api.smartsheet.com/2.0/favorites/workspace/{workspaceId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    objectId: 2252168947361668
};

// Remove workspace from list of favorites.
smartsheet.favorites.removeWorkspaceFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove workspace from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.WORKSPACE, new long[] { workspaceId });
// Remove workspace from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.WORKSPACE, new HashSet(Arrays.asList(workspaceId)));
# Remove workspace from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'workspace', 
    workspaceId
)

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 ACCESS_TOKEN
Returns Result object

Remove Favorites (in bulk)

Remove Favorite Sights

Example Request:

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

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 ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Folders

Example Request:

curl https://api.smartsheet.com/2.0/favorites/folder?objectIds={folderId1},{folderId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove folders from list of favorites.
smartsheet.favorites.removeFoldersFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove folders from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.FOLDER, new long[] { folderId, folderId2 });
// Remove folders from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.FOLDER, new HashSet(Arrays.asList(folderId1, folderId2)));
# Remove folders from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'folder', 
    [folderId1, folderId2]
)

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 ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Reports

Example Request:

curl https://api.smartsheet.com/2.0/favorites/report?objectIds={reportId1},{reportId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove reports from list of favorites.
smartsheet.favorites.removeReportsFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove reports from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.REPORT, new long[] { reportId1, reportId2 });
// Remove reports from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.REPORT, new HashSet(Arrays.asList(reportId1, reportId2)));
# Remove reports from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'report', 
    [reportId1, reportId2]
)

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 ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Sheets

Example Request:

curl https://api.smartsheet.com/2.0/favorites/sheet?objectIds={sheetId1},{sheetId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove sheets from list of favorites.
smartsheet.favorites.removeSheetsFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove sheets from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.SHEET, new long[] { sheetId1, sheetId2 });
// Remove sheets from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.SHEET, new HashSet(Arrays.asList(sheetId1, sheetId2)));
# Remove sheets from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'sheet', 
    [sheetId1, sheetId2]
)

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 ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Templates

Example Request:

curl https://api.smartsheet.com/2.0/favorites/template?objectIds={templateId1},{templateId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove templates from list of favorites.
smartsheet.favorites.removeTemplatesFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove templates from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.TEMPLATE, new long[] { templateId1, templateId2 });
// Remove templates from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.TEMPLATE, new HashSet(Arrays.asList(templateId1, templateId2)));
# Remove templates from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'template', 
    [templateId1, templateId2]
)

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 ACCESS_TOKEN
Parameters objectIds (required): a comma-separated list of object IDs representing the items to remove from Favorites
Returns Result object

Remove Favorite Workspaces

Example Request:

curl https://api.smartsheet.com/2.0/favorites/workspace?objectIds={workspaceId1},{workspaceId2} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    queryParameters: {
        objectIds: "2252168947361668, 2252168947361669"
    }
};

// Remove workspaces from list of favorites.
smartsheet.favorites.removeWorkspacesFromFavorites(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove workspaces from list of favorites.
smartsheet.FavoriteResources.RemoveFavorites(ObjectType.WORKSPACE, new long[] { workspaceId1, workspaceId2 });
// Remove workspaces from list of favorites.
smartsheet.favoriteResources().removeFavorites(FavoriteType.WORKSPACE, new HashSet(Arrays.asList(workspaceId1, workspaceId2)));
# Remove workspaces from list of favorites.
action = smartsheet.Favorites.remove_favorites(
    'workspace', 
    [workspaceId1, workspaceId2]
)

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 ACCESS_TOKEN
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

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:

curl https://api.smartsheet.com/2.0/folders/{folderId}/copy?include=all \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ \
    "destinationType": "folder", \
    "destinationId": 7960873114331012, \
    "newName": "newFolderName" \
}' \
-X POST
// Specify destination.
ContainerDestination destination = new ContainerDestination
{
    DestinationId = destinationFolderId,
    DestinationType = DestinationType.FOLDER,
    NewName = "newFolderName"
};

// Copy folder (omit 'include' and 'skipRemap' parameters).
smartsheet.FolderResources.CopyFolder(folderId, destination, null, null);

// Copy folder (specify 'include' parameter with value of "all", and 'skipRemap' parameter with value of "cellLinks").
smartsheet.FolderResources.CopyFolder(folderId, destination, new FolderCopyInclusion[] { FolderCopyInclusion.ALL }, new FolderRemapExclusion[] { FolderRemapExclusion.CELL_LINKS });
// Specify destination.
ContainerDestination destination = new ContainerDestination.AddContainerDestinationBuilder()
        .setDestinationType(DestinationType.FOLDER)
        .setDestinationId(destinationFolderId)
        .setNewName("newFolderName")
        .build();

// Copy folder (omit 'include' and 'skipRemap' parameters).
smartsheet.folderResources().copyFolder(folderId, destination, null, null);

// Copy folder (specify 'include' parameter with value of "all", and 'skipRemap' parameter with value of "cellLinks").
smartsheet.folderResources().copyFolder(folderId, destination, EnumSet.of(FolderCopyInclusion.ALL), EnumSet.of(FolderRemapExclusion.CELLLINKS));
# Copy folder to another folder.
action = smartsheet.Folders.copy_folder(
    folderId,
    smartsheet.models.ContainerDestination({
        'destination_id': destinationId,
        'destination_type': 'folder',
        'new_name': 'newFolderName'
    })
)

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 ACCESS_TOKEN
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 will not be 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 will be 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 will continue to point to the original source sheets.
  • If “reports” is specified in the skipRemap parameter value, the reports within the newly created folder will 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 will 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 will 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:

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

// Set options.
var options = {
    body: folder
};

// Create folder in "Sheets" folder (Home).
smartsheet.home.createFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder("New folder").Build();

// Create folder in "Sheets" folder (Home).
smartsheet.HomeResources.FolderResources.CreateFolder(folder);
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder().setName("New Folder").build();

// Create folder in "Sheets" folder (Home).
smartsheet.homeResources().folderResources().createFolder(folder);
# Create folder in "Sheets" folder (Home).
smartsheet.Home.create_folder('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 ACCESS_TOKEN
Content-Type: application/json
Request Body Folder object, limited to the following attribute:
  • name (string) - required, need not be unique
Returns Result object containing a Folder object for the newly created Folder

Create Folder (Folder)

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderid}/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New folder"}'
// Set folder name.
var folder = {
    "name": "New folder"
};

// Set options.
var options = {
    body: folder,
    folderId: 7960873114331012
};

// Create folder in another folder.
smartsheet.folders.createChildFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder("New folder").Build();

// Create folder in another folder.
smartsheet.FolderResources.CreateFolder(destinationFolderId, folder);
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder().setName("New Folder").build();

// Create folder in another folder.
smartsheet.folderResources().createFolder(destinationFolderId, folder);
# Create folder in another folder.
action = smartsheet.Folders.create_folder_in_folder(folderId, '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 ACCESS_TOKEN
Content-Type: application/json
Request Body Folder object, limited to the following attribute:
  • name (string) - required, need not be unique
Returns Result object containing a Folder object for the newly created Folder

Create Folder (Workspace)

Example Request:

curl https://api.smartsheet.com/2.0/workspaces/{workspaceid}/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{"name": "New folder"}'
// Set folder name.
var folder = {
    "name": "New folder"
};

// Set options.
var options = {
    body: folder,
    workspaceId: 1656220827314052
};

// Create folder in a workspace.
smartsheet.workspaces.createFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder("New folder").Build();

// Create folder in a workspace.
smartsheet.WorkspaceResources.FolderResources.CreateFolder(workspaceId, folder);
// Set folder name.
Folder folder = new Folder.CreateFolderBuilder().setName("New Folder").build();

// Create folder in a workspace.
smartsheet.workspaceResources().folderResources().createFolder(workspaceId, folder);
# Create folder in a workspace.
smartsheet.Workspaces.create_folder_in_workspace(workspaceId, '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 ACCESS_TOKEN
Content-Type: application/json
Request Body Folder object, limited to the following attribute:
  • name (string) - required, need not be unique
Returns Result object containing a Folder object for the newly created Folder

Delete Folder

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    id: 965780272637828 // ID of Folder
};

// Delete folder.
smartsheet.folders.deleteFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete folder.
smartsheet.FolderResources.DeleteFolder(folderId);
// Delete folder.
smartsheet.folderResources().deleteFolder(folderId);
# Delete folder.
smartsheet.Folders.delete_folder(folderId)

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 ACCESS_TOKEN
Returns Result object

Get Folder

Example Request:

curl https://api.smartsheet.com/2.0/folders/{folderId} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    id: 7116448184199044 // ID of Folder
};

// Get folder.
smartsheet.folders.getFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get folder (omit 'include' parameter).
smartsheet.FolderResources.GetFolder(folderId, null);

// Get folder (specify 'include' parameter with value of "source").
smartsheet.FolderResources.GetFolder(folderId, new FolderInclusion[] { FolderInclusion.SOURCE });
// Get folder (omit 'include' parameter).
smartsheet.folderResources().getFolder(folderId, null)

// Get folder (specify 'include' parameter with value of "source").
smartsheet.folderResources().getFolder(folderId, EnumSet.of(SourceInclusion.SOURCE))
# Get folder.
folder = smartsheet.Folders.get_folder(folderId)
# folder is an instance of smartsheet.models.Folder

Example Response:

{
    "id": 7116448184199044,
    "name": "Projects",
    "permalink": "https://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 ACCESS_TOKEN
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 (e.g., “folders”, “sheets”, etc.) will not be present in the response.

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

curl https://api.smartsheet.com/2.0/home/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json"
// List folders in "Sheets" folder. 
smartsheet.home.listFolders()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    })
// List folders in "Sheets" folder (omit pagination parameters).
smartsheet.HomeResources.FolderResources.ListFolders(null);

// List folders in "Sheets" folder (specify 'includeAll' parameter with value of "true").
smartsheet.HomeResources.FolderResources.ListFolders(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List folders (specify 'includeAll' parameter with value of "true").
smartsheet.homeResources().folderResources().listFolders(parameters);

// List folders (omit pagination parameters).
smartsheet.homeResources().folderResources().listFolders(null);
# Get complete list of folders in "Sheets" folder.
action = smartsheet.Home.list_folders(include_all=True)
home_sheets_folders = action.data

# Get paginated list of folders in "Sheets" folder.
action = smartsheet.Home.list_folders(page_size=5, page=1)
pages = action.total_pages
folders = action.data

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

curl https://api.smartsheet.com/2.0/folders/{folderId}/folders \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json"
// Set options.
var options = {
    folderId: 5107651446105988
};

// List folders in another folder.
smartsheet.folders.listChildFolders(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List folders in another folder (omit pagination parameters).
smartsheet.FolderResources.ListFolders(folderId, null);

// List folders in another folder (specify 'includeAll' parameter with value of "true").
smartsheet.FolderResources.ListFolders(folderId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List folders in another folder (specify 'includeAll' parameter with value of "true").
smartsheet.folderResources().listFolders(parameters);

// List folders in another folder (omit pagination parameters).
smartsheet.folderResources().listFolders(null);
# Get complete list of folders in another folder.
action = smartsheet.Folders.list_folders(folderId, include_all=True)
folders = action.data

# Get paginated list of folders in another folder.
action = smartsheet.Folders.list_folders(folderId, page_size=5, page=1)
pages = action.total_pages
folders = action.data

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 ACCESS_TOKEN
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 ACCESS_TOKEN" \
-H "Content-Type: application/json"
// Set options.
var options = {
    workspaceId: 1656220827314052
};

// List folders in workspace.
smartsheet.workspaces.listWorkspaceFolders(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List folders in workspace (omit pagination parameters).
smartsheet.WorkspaceResources.FolderResources.ListFolders(workspaceId, null);

// List folders in workspace (specify 'includeAll' parameter with value of "true").
smartsheet.WorkspaceResources.FolderResources.ListFolders(workspaceId, new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List folders in workspace (specify 'includeAll' parameter with value of "true").
smartsheet.workspaceResources().folderResources().listFolders(parameters);

// List folders in workspace (omit pagination parameters).
smartsheet.workspaceResources().folderResources().listFolders(null);
# Get complete list of folders in a workspace.
action = smartsheet.Workspaces.list_folders(workspaceId, include_all=True)
folders = action.data

# Get paginated list of folders in a workspace.
action = smartsheet.Workspaces.list_folders(workspaceId, page_size=5, page=1)
pages = action.total_pages
folders = action.data

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

curl https://api.smartsheet.com/2.0/folders/{folderId}/move \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ \
    "destinationType": "folder", \
    "destinationId": 7960873114331012, \
}' \
-X POST
// Specify destination.
ContainerDestination destination = new ContainerDestination
{
    DestinationId = destinationFolderId,
    DestinationType = DestinationType.FOLDER,
};

// Move folder.
smartsheet.FolderResources.MoveFolder(folderId, destination);
// Specify destination.
ContainerDestination destination = new ContainerDestination.AddContainerDestinationBuilder()
        .setDestinationType(DestinationType.FOLDER)
        .setDestinationId(destinationFolderId)
        .build();

// Move folder.
smartsheet.folderResources().moveFolder(folderId, destination);
# Move folder.
smartsheet.Folders.move_folder(
    folderId,
    smartsheet.models.Destination({
        'destination_id': folderId,
        'destination_type': 'folder'
    })
)

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

curl https://api.smartsheet.com/2.0/folders/{folderId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"name": "New name for folder"}'
// Set folder name.
var folder = {
    "name": "New name for folder"
};

// Set options.
var options = {
    id: 1486948649985924, // ID of Folder
    body: folder
};

// Update folder.
smartsheet.folders.updateFolder(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set folder name.
Folder folder = new Folder.UpdateFolderBuilder(folderId, "New name for folder").Build();

// Update folder.
smartsheet.FolderResources.UpdateFolder(folder);
// Set folder name and id of the folder to be updated.
Folder folder = new Folder.UpdateFolderBuilder().setName("New name for folder").setId(folderId).build();

// Update folder.
smartsheet.folderResources().updateFolder(folder);
# Update folder.
smartsheet.Folders.update_folder(folderId, '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 ACCESS_TOKEN
Content-Type: application/json
Request Body Folder object, limited to the following required attribute:
  • name (string)
Name need not be unique.
Returns Result object containing the updated Folder object

Groups

A Group is a collection of Group Members.

Objects

Group Object

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:

curl https://api.smartsheet.com/2.0/groups \
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-Type: application/json" \
-X POST \
-d '{ "name": "API-created Group", "description": "Group created via API", "members": [{ "email": "john.doe@smartsheet.com" }]}'
// Specify group.
var group = {
    "name": "API-created Group",
    "description": "Group created via API",
    "members": [
        {
            "email": "john.doe@smartsheet.com"
        }
    ]
};

// Set options.
var options = {
    body: group
};

// Create group.
smartsheet.groups.createGroup(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create group member.
GroupMember member = new GroupMember.AddGroupMemberBuilder("john.doe@smartsheet.com").Build();

// Add member to group.
Group group = new Group.CreateGroupBuilder("API-created Group", "Group created via API").SetMembers(new GroupMember[] { member }).Build();

// Create group.
smartsheet.GroupResources.CreateGroup(group);
// Create group member.
GroupMember member = new GroupMember.AddGroupMemberBuilder().setEmail("john.doe@smartsheet.com").build(); 

// Add member to group.
Group group = new Group.CreateGroupBuilder().setName("API-created Group").setDescription("Group created via API").setMembers(Arrays.asList(member)).build();

// Create group.
smartsheet.groupResources().createGroup(group);
# Create group (with a single member).
smartsheet.Groups.create_group(
    smartsheet.models.Group({
        'name': 'API-created Group',
        'description': 'Group created via API',
        'members': smartsheet.models.GroupMember({
            '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 ACCESS_TOKEN
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:

curl https://api.smartsheet.com/2.0/groups/{groupId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    id: 6932724448552836 // ID of Group
};

// Delete group.
smartsheet.groups.deleteGroup(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete group.
smartsheet.GroupResources.DeleteGroup(groupId);
// Delete group.
smartsheet.groupResources().deleteGroup(groupId);
# Delete group.
smartsheet.Groups.delete_group(groupId)

Example Response:

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

DELETE /groups/{groupId}

Deletes the Group specified in the URL.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Group

Example Request:

curl https://api.smartsheet.com/2.0/groups/{groupId} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    id: 4583173393803140 // ID of Group
};

// Get group.
smartsheet.groups.getGroup(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get group.
smartsheet.GroupResources.GetGroup(groupId);
// Get group.
smartsheet.groupResources().getGroup(groupId);
# Get group.
group = smartsheet.Groups.get_group(groupId)
# group is an instance of smartsheet.models.Group

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 ACCESS_TOKEN
Returns Group object that includes the list of GroupMembers

List All Org Groups

Example Request:

curl https://api.smartsheet.com/2.0/groups \
-H "Authorization: Bearer ACCESS_TOKEN"
// List all org groups.
smartsheet.groups.listGroups()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List all org groups (omit pagination parameters).
smartsheet.GroupResources.ListGroups(null);

// List all org groups (specify 'includeAll' parameter with value of "true").
smartsheet.GroupResources.ListGroups(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll'
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List all org groups (specify 'includeAll' parameter with value of "true").
smartsheet.groupResources().listGroups(parameters);

// List all org groups (omit pagination parameters).
smartsheet.groupResources().listGroups(null);
# Get all org groups.
action = smartsheet.Groups.list_groups(include_all=True)
groups = action.data

# Get paginated list of org groups.
action = smartsheet.Groups.list_groups(page_size=10, page=1)
pages = action.total_pages
groups = action.data

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 1,
    "data": [
        {
            "id": 4583173393803140,
            "name": "Group 1",
            "description": "My group",
            "owner": "john.doe@smartsheet.com",
            "ownerId": 2331373580117892,
            "createdAt": "2014-05-29T14:41:35-07:00",
            "modifiedAt": "2014-05-29T14:41:35-07:00"
        }
    ]
}

GET /groups

Gets 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 ACCESS_TOKEN
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:

curl https://api.smartsheet.com/2.0/groups/{groupId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{ "name": "Renamed Group", "description": "Some new description" }'
// Specify the name and description of the group.
var group = {
    "name": "Renamed Group",
    "description": "Some new description"
};

// Set options.
var options = {
    body: group,
    id: 2331373580117892 // ID of Group
};

// Update group.
smartsheet.groups.updateGroup(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify the name and description of the group.
Group group = new Group.UpdateGroupBuilder(groupId).SetName("Renamed Group").SetDescription("Some new description").Build();

// Update group.
smartsheet.GroupResources.UpdateGroup(group);
// Specify the name and description of the group.
Group group = new Group.UpdateGroupBuilder().setId(groupId).setName("Renamed Group").setDescription("Some new description").build();

// Update group.
smartsheet.groupResources().updateGroup(group);
# Update group.
smartsheet.Groups.update_group(
    groupId,
    smartsheet.models.Group({
        '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 ACCESS_TOKEN
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 will be 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

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 Member(s)

Example Request:

curl https://api.smartsheet.com/2.0/groups/{groupId}/members \
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-Type: application/json" \
-X POST \
-d '[{ "email": "jane.doe@smartsheet.com" }]'
// Specify group member(s).
var members = [{ "email": "jane.doe@smartsheet.com" }];

// Set options.
var options = {
    body: members,
    groupId: 7917992160847748
};

// Add member(s) to group.
smartsheet.groups.addGroupMembers(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Create group member.
GroupMember member = new GroupMember.AddGroupMemberBuilder("jane.doe@smartsheet.com").Build();

// Add member(s) to group.
smartsheet.GroupResources.AddGroupMembers(groupId, new GroupMember[] { member });
// Create group member.
GroupMember member = new GroupMember.AddGroupMemberBuilder().setEmail("jane.doe@smartsheet.com").build();

// Add member(s) to group.
smartsheet.groupResources().memberResources().addGroupMembers(groupId, Arrays.asList(member));
# Add member(s) to group.
smartsheet.Groups.add_members(
    groupId,
    [smartsheet.models.GroupMember({'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 will be returned. If called with an array of GroupMember objects any users specified in the array that are already group members will be ignored and omitted from the response.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body A single GroupMember object or an array of Group Member objects, limited to the following attribute:
  • email
Returns Result object containing the members added to the group – either a single group member or array of group member objects, corresponding to what was specified in the request.
Errors If an error occurs because the request specified one or more alternate email addresses (i.e., not the primary email address associated with the User account), the Error object returned will contain 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 using their primary address u1@smartsheet.com.”
  “detail”: [
      {
        “alternateEmailAddress”: “u1+1@smartsheet.com”,
        “primaryEmailAddress”: “u1@smartsheet.com”
      }
  ]
}

Remove Group Member

Example Request:

curl https://api.smartsheet.com/2.0/groups/{groupId}/members/{userId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    groupId: 7917992160847748,
    userId: 1539725208119172
};

// Remove member from group.
smartsheet.groups.removeGroupMember(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Remove member from group.
smartsheet.GroupResources.RemoveGroupMember(groupId, userId);
// Remove member from group.
smartsheet.groupResources().memberResources().deleteGroupMember(groupId, userId)
# Remove member from group.
smartsheet.Groups.remove_member(groupId, groupMemberId)

Example Response:

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

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

Removes a member from a Group.

Access Scope ADMIN_USERS
Headers Authorization: Bearer ACCESS_TOKEN
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

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 All Contents

Example Request:

curl https://api.smartsheet.com/2.0/home?include=source \
-H "Authorization: Bearer ACCESS_TOKEN"
// List all contents.
smartsheet.home.listContents()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log(error);
    });
// List all contents (omit 'include' parameter).
smartsheet.HomeResources.GetHome(null);

// List all contents (specify 'include' parameter with value of "source").
smartsheet.HomeResources.GetHome(new HomeInclusion[] { HomeInclusion.SOURCE });
// List all contents (omit 'include' parameter).
smartsheet.homeResources().getHome(null);

// List all contents (specify 'include' parameter with value of "source").
smartsheet.homeResources().getHome(EnumSet.of(SourceInclusion.SOURCE)));
# List all contents (include source).
contents = smartsheet.Home.list_all_contents(include='source')

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 ACCESS_TOKEN
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 (i.e., at the Home level), see Folders.

Home Sheets

For details about working with sheets in the user’s Sheets folder (i.e., 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

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 column(s), 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:

curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    id: 4583173393803140 // ID of Report
};

// Get report.
smartsheet.reports.getReport(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get report (omit 'include', 'pageSize', and 'page' parameters).
smartsheet.ReportResources.GetReport(reportId, null, null, null);

// Get report (specify 'include' parameter with value of "attachments" and "discussions", 'pageSize' parameter with value of "500", and 'page' of value "2").
smartsheet.ReportResources.GetReport(reportId, new ReportInclusion[] { ReportInclusion.ATTACHMENTS, ReportInclusion.DISCUSSIONS }, 500, 2);
// Get report (omit 'include', 'pageSize', and 'page' parameters).
smartsheet.reportResources().getReport(reportId, null, null, null);

// Get report (specify 'include' parameter with value of "attachments" and "discussions", 'pageSize' parameter with value of "500", and 'page' of value "2").
smartsheet.reportResources().getReport(reportId, EnumSet.of(ReportInclusion.ATTACHMENTS, ReportInclusion.DISCUSSIONS), 500, 2)
# Get report.
report = smartsheet.Reports.get_report(reportId)

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",
            "sheetNameColumn": true
        },
        {
            "virtualId": 2331373580117892,
            "index": 1,
            "title": "Status",
            "type": "TEXT_NUMBER"
        }
    ],
    "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 ACCESS_TOKEN
Parameters include (optional) – a comma-separated list of optional elements to include in the response:
  • discussions
  • attachments
  • format
  • sourceSheets
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 will be returned.
Returns Report object, populated according to the “include” parameter

Get Report as Excel / CSV

Example Request (Excel):

curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/vnd.ms-excel" \
-o output.xlsx
// Set options.
var options = {
    id: 3882962191181700 // ID of Report
};

// Get report as Excel.
smartsheet.reports.getReportAsExcel(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get report as Excel.
smartsheet.ReportResources.GetReportAsExcel(reportId, outputStream);
// Get report as Excel.
smartsheet.reportResources().getReportAsExcel(reportId, outputStream);
# Get report as Excel (download file with filename suggested by API).
smartsheet.Reports.get_report_as_excel(
    reportId,
    download_folder_path
)

# Get report as Excel (specify custom filename for the downloaded file).
smartsheet.Reports.get_report_as_excel(
    reportId,
    download_folder_path,
    'MyFileName.xslx'
)

Example Response:

# See local file named "output.xlsx"
// [todo]
// Contents of Excel file will be written to "outputStream"
// Contents of Excel file will be written to "outputStream"
# download folder will contain the downloaded Excel file

Example Request (CSV):

curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: text/csv" \
-o output.csv
// Set options.
var options = {
    id: 3882962191181700 // ID of Report
};

// Get report as CSV.
smartsheet.reports.getReportAsCSV(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get report as CSV.
smartsheet.ReportResources.GetReportAsCSV(reportId, outputStream);
// Get report as CSV.
smartsheet.reportResources().getReportAsCsv(reportId, outputStream);
# Get report as CSV (download file with filename suggested by API).
smartsheet.Reports.get_report_as_csv(
    reportId,
    download_folder_path
)

# Get report as CSV (specify custom filename for the downloaded file).
smartsheet.Reports.get_report_as_csv(
    reportId,
    download_folder_path,
    'CallMeAl.csv'
)

Example Response:

# See local file named "output.csv"
// [todo]
// Contents of CSV file will be written to "outputStream"
// Contents of CSV file will be written to "outputStream"
# download folder will contain the downloaded CSV file

GET /reports/{reportId}

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

Access Scope READ_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Accept – must be set to one of the following values:
  • application/vnd.ms-excel
  • text/csv
Returns The file in either Excel or CSV format, containing the Report data according to the include parameter.

List Reports

Example Request:

curl https://api.smartsheet.com/2.0/reports 
-H "Authorization: Bearer ACCESS_TOKEN"
// List reports.
smartsheet.reports.listReports()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// List reports (omit pagination parameters).
smartsheet.ReportResources.ListReports(null);

// List reports (specify 'includeAll' parameter with value of "true").
smartsheet.ReportResources.ListReports(new PaginationParameters(true, null, null));
// Specify pagination parameter 'includeAll' 
PaginationParameters parameters = new PaginationParameters.PaginationParametersBuilder().setIncludeAll(true).build();

// List reports (specify 'includeAll' parameter with value of "true").
smartsheet.reportResources().listReports(parameters);

// List reports (omit pagination parameters).
smartsheet.reportResources().listReports(null);
# Get all reports.
action = smartsheet.Reports.list_reports(include_all=True)
reports = action.data

# Get paginated list of reports.
action = smartsheet.Reports.list_reports(page_size=5, page=1)
pages = action.total_pages
reports = action.data

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 ACCESS_TOKEN
Parameters modifiedSince (optional): when specified with a date and time value, response will only include 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:

curl https://api.smartsheet.com/2.0/reports/{reportId}/publish \
-H "Authorization: Bearer ACCESS_TOKEN"
// [todo]
// [todo]
// [todo]
# [todo]

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 ACCESS_TOKEN
Returns ReportPublish object

Set Report Publish Status

Example Request:

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

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

curl https://api.smartsheet.com/2.0/reports/{reportId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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"}}'
// Configure email.
var email = {
    "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"
    }
};

// Set options.
var options = {
    body: email,
    reportId: 8130994621441924
};

// Send report via email.
smartsheet.reports.sendReportViaEmail(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "john.doe@smartsheet.com" }, 
    new Recipient { GroupId = 2258118617917316 } 
};

// Configure email.
SheetEmail sheetEmail = new SheetEmail { 
    SendTo = recipients, 
    Subject = "Check this report out!", 
    Message = "Here is the report I mentioned in our meeting", 
    CcMe = false, 
    Format = SheetEmailFormat.PDF, 
    FormatDetails = new FormatDetails { PaperSize = PaperSize.A4 } 
};

// Send report via email.
smartsheet.ReportResources.SendReport(reportId, sheetEmail);
// Specify an individual recipient.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("john.doe@smartsheet.com").build();

// Specify a group recipient.
RecipientGroup recipientGroup = new RecipientGroup.AddRecipientGroupBuilder().setGroupId(2258118617917316).build();

/// Set recipients.
List<Recipient> recipients = Arrays.asList(recipientEmail, recipientGroup);

// Set format details.
FormatDetails formatDetails = new FormatDetails();
formatDetails.setPaperSize(PaperSize.A0); 

// Configure email.
SheetEmail email = new SheetEmail.AddSheetEmailBuilder()
    .setSendTo(recipients)
    .setSubject("Check this report out!")
    .setMessage("Here is the report I mentioned in our meeting")
    .setCcMe(false)
    .setFormat(SheetEmailFormat.PDF)
    .setFormatDetails(formatDetails)
    .build();

// Send report via email.
smartsheet.reportResources().sendReport(reportId, email)
# Send report via email.
action = smartsheet.Reports.send_report(
    reportId,
    smartsheet.models.SheetEmail({
        'send_to': smartsheet.models.Recipient({
            'email': 'john.doe@smartsheet.com'
        }),
        'subject': 'Check this report out!',
        'message': 'Here is the report I mentioned in our meeting.',
        'cc_me': False,
        'format': 'PDF',
        'format_details': smartsheet.models.FormatDetails({
            'paper_size': '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 ACCESS_TOKEN
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

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 will never be 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 will never be 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 will never be 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 Row(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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} ] }]'
// Specify rows.
var row = [
    {
        "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
            }
        ]
    }
];

// Set options.
var options = {
    body: row,
    sheetId: 2252168947361668
};

// Add rows to sheet.
smartsheet.sheets.addRows(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify cell values for first row.
Cell[] cellsA = new Cell[] { new Cell.AddCellBuilder(7960873114331012, true).Build(), new Cell.AddCellBuilder(642523719853956, "New status").SetStrict(false).Build() };

// Specify contents of first row.
Row rowA = new Row.AddRowBuilder(true, null, null, null, null).SetCells(cellsA).Build();

// Specify cell values of second row.
Cell[] cellsB = new Cell[] { new Cell.AddCellBuilder(7960873114331012, true).Build(), new Cell.AddCellBuilder(642523719853956, "New status").SetStrict(false).Build() };

// Specify contents of second row.
Row rowB = new Row.AddRowBuilder(true, null, null, null, null).SetCells(cellsB).Build();

// Add rows to sheet.
smartsheet.SheetResources.RowResources.AddRows(sheetId, new Row[] { rowA, rowB });
// Specify cell values for first row.
List<Cell> cellsA = new Cell.AddRowCellsBuilder().addCell(7960873114331012, true).addCell(642523719853956, "New status").build();

// Specify contents of first row.
Row rowA = new Row.AddRowBuilder().setCells(cellsA).setToBottom(true).build();

// Specify cell values for second row.
List<Cell> cellsB = new Cell.AddRowCellsBuilder().addCell(7960873114331012, true).addCell(642523719853956, "New status").build();

// Specify contents of second row.
Row rowB = new Row.AddRowBuilder().setCells(cellsB).setToBottom(true).build();

// Add rows to sheet.
smartsheet.sheetResources().rowResources().addRows(sheetId, Arrays.asList(rowA, rowB));
# Specify cell values for one row.
row_a = smartsheet.models.Row()
row_a.to_top = True
row_a.cells.append({
    'column_id': 7960873114331012,
    'value': True
})
row_a.cells.append({
    'column_id': 642523719853956
    'value': 'New Status',
    'strict': False
})

# Specify cell values for another row.
row_b = smartsheet.models.Row()
row_b.to_top = True
row_b.cells.append({
    'column_id': 7960873114331012,
    'value': True
})
row_b.cells.append({
    'column_id': 642523719853956
    'value': 'New Status',
    'strict': False
})

# Add rows to sheet.
action = smartsheet.Sheets.add_rows(sheetId, [row_a, row_b])

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 ACCESS_TOKEN
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.
Request Body Row object or an array of Row objects, with the following attributes:
  • One or more location-specifier attributes (optional)
  • format (optional)
  • expanded (optional)
  • locked (optional)
  • A cells attribute set to an array of Cell objects. To insert an empty row, set the cells attribute to empty or null. Each Cell object may contain the following attributes:
    • columnId (required)
    • value (required)
    • strict (optional)
    • format (optional)
    • hyperlink (optional)
Please note the following:
  • Column Ids must be valid for the sheet specified, and must only be used once for each row in the operation.
  • Cells of a project sheet in the “Predecessor” or “Finish Date” columns cannot be populated via API.
  • Cells of a project sheet in the “Start Date” column cannot be populated via API for rows that also specify a value in the “Predecessor” column.
More information:
Returns Result object containing the newly created row(s) – 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 will contain 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 will fail (no rows will be added), and the Error response returned will describe 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 will contain 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 Row(s) to Another Sheet

Example Request:

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

// Set options.
var options = {
    body: copyRow,
    sheetId: 2252168947361668
};

// Copy rows.
smartsheet.sheets.copyRowToAnotherSheet(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify destination sheet.
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination { SheetId = 2258256056870788 };

// Specify rows to be copied (and destination sheet).
CopyOrMoveRowDirective directive = new CopyOrMoveRowDirective { RowIds = new long[] { 145417762563972, 8026717110462340 }, To = destination };

// Copy rows (omit 'include' and 'ignoreRowsNotFound' parameters).
smartsheet.SheetResources.RowResources.CopyRowsToAnotherSheet(sheetId, directive, null, null);

// Copy rows (specify 'include' parameter with value of "children", and 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.SheetResources.RowResources.CopyRowsToAnotherSheet(sheetId, directive, new CopyRowInclusion[] { CopyRowInclusion.CHILDREN }, true);
// Specify destination sheet.
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination.InsertCopyOrMoveRowDestinationBuilder().setSheetId(2258256056870788).build();

// Specify rows to be copied (and destination sheet).
CopyOrMoveRowDirective directive = new CopyOrMoveRowDirective.InsertCopyOrMoveRowDirectiveBuilder().setRowIds(Arrays.asList(145417762563972, 8026717110462340)).setTo(destination).build();

// Copy rows (omit 'include' and 'ignoreRowsNotFound' parameters).
smartsheet.sheetResources().rowResources().copyRows(sheetId, null, null, directive);

// Copy rows (specify 'include' parameter with value of "children", and 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.sheetResources().rowResources().copyRows(sheetId, EnumSet.of(RowCopyInclusion.CHILDREN), true, directive);
# Copy rows from one sheet to another sheet.
smartsheet.Sheets.copy_rows(
    sheetId,
    smartsheet.models.CopyOrMoveRowDirective({
        'row_ids': [145417762563972, 8026717110462340]
        'to': smartsheet.models.CopyOrMoveRowDestination({
            'sheet_id': 2258256056870788
        })
    })
)

Example Response:

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

POST /sheets/{sheetId}/rows/copy

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

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
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 will also be copied to the destination sheet, and parent-child relationships amongst rows will be preserved within the destination sheet; if not specified, only the rows specified in the request will be 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 will not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet will cause an error response (and no rows will be copied).
Request Body CopyOrMoveRowDirective object
Returns CopyOrMoveRowResult object

Delete Row(s)

Example Request:

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

// Delete row.
smartsheet.sheets.deleteRow(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete rows (specify 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.SheetResources.RowResources.DeleteRows(sheetId, new long[] { rowId1, rowId2, rowId3 }, true);
// Delete rows (specify 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.sheetResources().rowResources().deleteRows(sheetId, new HashSet(Arrays.asList(rowId1, rowId2, rowId3), true);
# Delete rows.
smartsheet.Sheets.delete_rows(sheetId, [rowId1, rowId2, rowId3])

Example Response:

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

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

Deletes one or more row(s) from the Sheet specified in the URL.

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
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 will be deleted, and the “not found” error will be 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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}?include=discussions,attachments,columns,columnType \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 4583173393803140,
    rowId: 2361756178769796
};

// Get row.
smartsheet.sheets.getRow(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get row (omit 'include' parameter and pagination parameters).
smartsheet.SheetResources.RowResources.GetRow(sheetId, rowId, null, null);

// Get row (specify 'include' parameter with values of "columns" and "columnType", and 'exclude' parameter with value of "nonexistentCells").
smartsheet.SheetResources.RowResources.GetRow(sheetId, rowId, new RowInclusion[] { RowInclusion.COLUMNS, RowInclusion.COLUMN_TYPE }, new ObjectExclusion[] { ObjectExclusion.NONEXISTENT_CELLS });
// Get row (omit 'include' parameter and pagination parameters).
smartsheet.sheetResources().rowResources().getRow(sheetId, rowId, null, null);

// Get row (specify 'include' parameter with values of "columns" and "columnType", and 'exclude' parameter with value of "nonexistentCells").
smartsheet.sheetResources().rowResources().getRow(sheetId, rowId, EnumSet.of(RowInclusion.COLUMNS, RowInclusion.COLUMN_TYPE), EnumSet.of(ObjectExclusion.NONEXISTENT_CELLS));
# Get row (include discussions, attachments, columns, and columnType).
row = smartsheet.Sheets.get_row(
    sheetId, 
    rowId, 
    include='discussions,attachments,columns,columnType'
)

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 ACCESS_TOKEN
Parameters include (optional) – comma-separated list of elements to include in the response.

See Row Include Flags.
Also supports the columns include flag, which will add 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): when specified with a value of “nonexistentCells”, response will not include cells that have never contained any data
Returns Row object

List Rows

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

Move Row(s) to Another Sheet

Example Request:

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

// Set options.
var options = {
    body: moveRow,
    sheetId: 2252168947361668
};

// Move rows.
smartsheet.sheets.moveRowToAnotherSheet(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    }
// Specify destination sheet.
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination { SheetId = 2258256056870788 };

// Specify rows to be moved (and destination sheet).
CopyOrMoveRowDirective directive = new CopyOrMoveRowDirective { RowIds = new long[] { 145417762563972, 8026717110462340 }, To = destination };

// Move rows (omit 'include' and 'ignoreRowsNotFound' parameters).
smartsheet.SheetResources.RowResources.MoveRowsToAnotherSheet(sheetId, directive, null, null);

// Move rows (specify 'include' parameter with value of "attachments" and "discussions", and 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.SheetResources.RowResources.MoveRowsToAnotherSheet(sheetId, directive, new MoveRowInclusion[] { MoveRowInclusion.ATTACHMENTS, MoveRowInclusion.DISCUSSIONS }, true);
// Specify destination sheet.
CopyOrMoveRowDestination destination = new CopyOrMoveRowDestination.InsertCopyOrMoveRowDestinationBuilder().setSheetId(2258256056870788).build();

// Specify rows to be moved (and destination sheet).
CopyOrMoveRowDirective directive = new CopyOrMoveRowDirective.InsertCopyOrMoveRowDirectiveBuilder().setRowIds(Arrays.asList(145417762563972, 8026717110462340)).setTo(destination).build();

// Move rows (omit 'include' and 'ignoreRowsNotFound' parameters).
smartsheet.sheetResources().rowResources().moveRows(sheetId, null, null, directive);

// Move rows (specify 'include' parameter with value of "attachments" and "discussions", and 'ignoreRowsNotFound' parameter with value of "true").
smartsheet.sheetResources().rowResources().moveRows(sheetId, EnumSet.of(EnumSet.of(RowMoveInclusion.ATTACHMENTS, RowMoveInclusion.DISCUSSIONS)), true, directive);
# Move rows from one sheet to another sheet.
smartsheet.Sheets.move_rows(
    sheetId,
    smartsheet.models.CopyOrMoveRowDirective({
        'row_ids': [145417762563972, 8026717110462340],
        'to': smartsheet.models.CopyOrMoveRowDestination({
            'sheet_id': 2258256056870788
        })
    })
)

Example Response:

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

POST /sheets/{sheetId}/rows/move

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

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
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 will not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet will cause an error response (and no rows will be moved).
Request Body CopyOrMoveRowDirective object
Returns CopyOrMoveRowResult object

Send Row(s) via Email

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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 \
}'
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "recipient@smartsheet.com" }, 
};

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail {
    SendTo = recipients,
    Subject = "some subject",
    Message = "some message",
    CcMe = false,
    RowIds = new long[] { rowId1, rowId2 },
    ColumnIds = new long[] { columnId1, columnId2 },
    IncludeAttachments = false,
    IncludeDiscussions = false
};

// Send rows via email.
smartsheet.SheetResources.RowResources.SendRows(sheetId, multiRowEmail);
// Specify recipients.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("recipient@smartsheet.com").build();

List<Recipient> recipients = new ArrayList<Recipient>();
recipients.add(recipientEmail);

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()
    .setSendTo(recipients)
    .setSubject("some subject")
    .setMessage("some message")
    .setCcMe(false)
    .setRowIds(Arrays.asList(rowId1, rowId2)
    .setColumnIds(Arrays.asList(columnId1, columnId2)
    .setIncludeAttachments(false)
    .setIncludeDiscussions(false)
    .build();

// Send rows via email.
smartsheet.sheetResources().rowResources().sendRows(sheetId, multiRowEmail);
# Configure email.
email = smartsheet.models.MultiRowEmail()
email.send_to = smartsheet.models.Recipient({
    'email': 'john.doe@smartsheet.com'
})
email.row_ids = [rowId1, rowId2]
email.column_ids = [columnId1, columnId2]

# Send rows via email.
smartsheet.Sheets.send_rows(sheetId, email)

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 ACCESS_TOKEN
Content-Type: application/json
Request Body MultiRowEmail object.

The columns included for each row in the email will be 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 will be 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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient1@smartsheet.com"}, \
        {"email": "recipient2@smartsheet.com"} \
    ], \
    "subject": "some subject", \
    "message": "some message", \
    "ccMe": false, \
    "rowIds": [4508292249610116, 2256492435924868], \
    "columnIds": [4508284196546436, 2256484382861188], \
    "includeAttachments": false, \
    "includeDiscussions": false \
}'
// [todo]
// [todo]
# [todo]

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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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 ACCESS_TOKEN
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 will be 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 (i.e., not the primary email address associated with the User account), the Error object returned will contain 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 Row(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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"}]}]'
// Specify updated cell values.
var row = [
    {
        "id": "6572427401553796",
        "cells": [
            {
                "columnId": 7518312134403972,
                "value": "new value"
            },
            {
                "columnId": 1888812600190852,
                "value": "A"
            }
        ]
    },
    {
        "id": "2068827774183300",
        "cells": [
            {
                "columnId": 7518312134403972,
                "value": "desc_updated"
            },
            {
                "columnId": 1888812600190852,
                "value": "B"
            }
        ]
    }
];

// Set options.
var options = {
    body: row,
    sheetId: 2252168947361668
};

// Update rows in sheet.
smartsheet.sheets.updateRow(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify updated cell values for first row.
Cell[] cellsA = new Cell[] { new Cell.UpdateCellBuilder(7518312134403972, "new value").Build(), new Cell.UpdateCellBuilder(1888812600190852, "A").Build() };

// Specify updated contents of first row.
Row rowA = new Row.UpdateRowBuilder(6572427401553796).SetCells(cellsA).Build();

// Specify updated cell values for second row.
Cell[] cellsB = new Cell[] { new Cell.UpdateCellBuilder(7518312134403972, "desc_updated").Build(), new Cell.UpdateCellBuilder(1888812600190852, "B").Build() };

// Specify updated contents of second row.
Row rowB = new Row.UpdateRowBuilder(2068827774183300).SetCells(cellsB).Build();

// Update rows in sheet.
smartsheet.SheetResources.RowResources.UpdateRows(sheetId, new Row[] { rowA, rowB });
// Specify updated cell values for first row.
List<Cell> cellsA = new Cell.UpdateRowCellsBuilder().addCell(7518312134403972, "new value").addCell(1888812600190852, "A").build();

// Specify updated contents of first row.
Row rowA = new Row.UpdateRowBuilder().setCells(cellsA).setRowId(6572427401553796).build();

// Specify updated cell values for second row.
List<Cell> cellsB = new Cell.UpdateRowCellsBuilder().addCell(7518312134403972, "desc_updated").addCell(1888812600190852, "B").build();

// Specify updated contents of second row.
Row rowB = new Row.UpdateRowBuilder().setCells(cellsB).setRowId(2068827774183300).build();

// Update rows in sheet.
smartsheet.sheetResources().rowResources().updateRows(sheetId, Arrays.asList(rowA, rowB));
# Specify updated cell values for one row.
row_a = smartsheet.Sheets.get_row(sheetId, 6572427401553796)

# use row get_column(columnId) convenience method to pluck the 
# cell with a known columnId out of the row
cell_a = row_a.get_column(7518312134403972)
cell_a.value = 'new value'
cell_b = row_a.get_column(1888812600190852)
cell_b.value = 'A'

# use row set_column(id, Cell) convenience method
# to replace the cell in-place.
row_a.set_column(cell_a.column_id, cell_a)
row_a.set_column(cell_b.column_id, cell_b)

# Specify updated cell values for a second row.
row_b = smartsheet.Sheets.get_row(sheetId, 2068827774183300)
cell_c = row_b.get_column(7518312134403972)
cell_c.value = 'desc_updated'
cell_d = row_b.get_column(1888812600190852)
cell_d.value = 'B'
row_b.set_column(cell_c.column_id, cell_c)
row_b.set_column(cell_d.column_id, cell_d)

# Update rows.
smartsheet.Sheets.update_rows(sheetId, [row_a, row_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 row(s), expands/collapses the specified row(s), and/or modifies the position of specified rows (including indenting/outdenting).

Access Scope WRITE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
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.
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)
    • value (required)
    • strict (optional)
    • format (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
  • 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 containing formulas cannot be updated.
  • Cells of a project sheet in the “Predecessor” or “Finish Date” columns 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 will occur without warning. Empty string values are converted to null.
Returns Result object containing an array of the updated row(s).
Errors When allowPartialSuccess=false (or not specified):

If an error occurs, the Error object returned will contain 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 will fail (no rows will be updated), and the Error response returned will describe 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 will contain 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 (e.g. 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 Values.

Row Location

When using the Add Row(s) operation to insert new rows into a sheet or the Update Row(s) 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
  • toBotom
  • 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 attribute(s) should be set to implement various actions.

Action Row attribute(s)
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)

Searching

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

Objects

SearchResult Object

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:

curl https://api.smartsheet.com/2.0/search?query=stuff \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    query: "stuff"
};

// Search everything.
smartsheet.search.searchAll(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set search criteria.
string query = "stuff";

// Search everything.
smartsheet.SearchResources.Search(query);
// Set search criteria.
string query = "stuff";

// Search everything.
smartsheet.searchResources().search(query);
# Set search criteria.
query = 'stuff'

# Search everything.
result = smartsheet.Search.search(query)
# result is a smartsheet.models.SearchResult object

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 ACCESS_TOKEN
Parameters query (required): Text with which to perform the search.
Returns SearchResult object that contains a maximum of 100 SearchResultems

Search Sheet

Example Request:

curl https://api.smartsheet.com/2.0/search/sheets/{sheetId}?query=stuff \
-H "Authorization: Bearer ACCESS_TOKEN"
// Set options.
var options = {
    sheetId: 1888207043356548,
    queryParameters: {
        query: "stuff"
    }
};

// Search sheet.
smartsheet.search.searchSheet(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Set search criteria.
string query = "stuff";

// Search sheet.
smartsheet.SearchResources.SearchSheet(sheetId, query);
// Set search criteria.
string query = "stuff";

// Search sheet.
smartsheet.searchResources().searchSheet(sheetId, query);
# Set search criteria.
query = 'stuff'

# Search sheet.
result = smartsheet.Search.search_sheet(sheetId, query)
# result is a smartsheet.models.SearchResult object

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 ACCESS_TOKEN
Parameters query (required): Text with which to perform the search.
Returns SearchResult object that contains a maximum of 100 SearchResultems

Sending via Email

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

Objects

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:

curl https://api.smartsheet.com/2.0/reports/{reportId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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"}}'
// Configure email.
var email = {
    "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"
    }
};

// Set options.
var options = {
    body: email,
    reportId: 8130994621441924
};

// Send report via email.
smartsheet.reports.sendReportViaEmail(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "john.doe@smartsheet.com" }, 
    new Recipient { GroupId = 2258118617917316 } 
};

// Configure email.
SheetEmail sheetEmail = new SheetEmail { 
    SendTo = recipients, 
    Subject = "Check this report out!", 
    Message = "Here is the report I mentioned in our meeting", 
    CcMe = false, 
    Format = SheetEmailFormat.PDF, 
    FormatDetails = new FormatDetails { PaperSize = PaperSize.A4 } 
};

// Send report via email.
smartsheet.ReportResources.SendReport(reportId, sheetEmail);
// Specify an individual recipient.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("john.doe@smartsheet.com").build();

// Specify a group recipient.
RecipientGroup recipientGroup = new RecipientGroup.AddRecipientGroupBuilder().setGroupId(2258118617917316).build();

/// Set recipients.
List<Recipient> recipients = Arrays.asList(recipientEmail, recipientGroup);

// Set format details.
FormatDetails formatDetails = new FormatDetails();
formatDetails.setPaperSize(PaperSize.A0); 

// Configure email.
SheetEmail email = new SheetEmail.AddSheetEmailBuilder()
    .setSendTo(recipients)
    .setSubject("Check this report out!")
    .setMessage("Here is the report I mentioned in our meeting")
    .setCcMe(false)
    .setFormat(SheetEmailFormat.PDF)
    .setFormatDetails(formatDetails)
    .build();

// Send report via email.
smartsheet.reportResources().sendReport(reportId, email)
# Send report via email.
action = smartsheet.Reports.send_report(
    reportId,
    smartsheet.models.SheetEmail({
        'send_to': smartsheet.models.Recipient({
            'email': 'john.doe@smartsheet.com'
        }),
        'subject': 'Check this report out!',
        'message': 'Here is the report I mentioned in our meeting.',
        'cc_me': False,
        'format': 'PDF',
        'format_details': smartsheet.models.FormatDetails({
            'paper_size': '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 ACCESS_TOKEN
Content-Type: application/json
Request Body SheetEmail object
Returns Result object

Send Row(s)

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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 \
}'
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "recipient@smartsheet.com" }, 
};

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail {
    SendTo = recipients,
    Subject = "some subject",
    Message = "some message",
    CcMe = false,
    RowIds = new long[] { rowId1, rowId2 },
    ColumnIds = new long[] { columnId1, columnId2 },
    IncludeAttachments = false,
    IncludeDiscussions = false
};

// Send rows via email.
smartsheet.SheetResources.RowResources.SendRows(sheetId, multiRowEmail);
// Specify recipients.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("recipient@smartsheet.com").build();

List<Recipient> recipients = new ArrayList<Recipient>();
recipients.add(recipientEmail);

// Configure email.
MultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()
    .setSendTo(recipients)
    .setSubject("some subject")
    .setMessage("some message")
    .setCcMe(false)
    .setRowIds(Arrays.asList(rowId1, rowId2)
    .setColumnIds(Arrays.asList(columnId1, columnId2)
    .setIncludeAttachments(false)
    .setIncludeDiscussions(false)
    .build();

// Send rows via email.
smartsheet.sheetResources().rowResources().sendRows(sheetId, multiRowEmail);
# Configure email.
email = smartsheet.models.MultiRowEmail()
email.send_to = smartsheet.models.Recipient({
    'email': 'john.doe@smartsheet.com'
})
email.row_ids = [rowId1, rowId2]
email.column_ids = [columnId1, columnId2]

# Send rows via email.
smartsheet.Sheets.send_rows(sheetId, email)

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 ACCESS_TOKEN
Content-Type: application/json
Request Body MultiRowEmail object.

The columns included for each row in the email will be 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 will be 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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/emails \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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"}}'

// Configure email.
var email = {
    "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"
    }
};

// Set options.
var options = {
    body: email,
    sheetId: 2252168947361668
};

// Send sheet via email.
smartsheet.sheets.sendSheetViaEmail(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Specify recipients.
Recipient[] recipients = new Recipient[] { 
    new Recipient { Email = "john.doe@smartsheet.com" }, 
    new Recipient { GroupId = 2258118617917316 } 
};

// Configure email.
SheetEmail sheetEmail = new SheetEmail { 
    SendTo = recipients, 
    Subject = "Check this report out!", 
    Message = "Here are the rows I mentioned in our meeting", 
    CcMe = false, 
    Format = SheetEmailFormat.PDF, 
    FormatDetails = new FormatDetails { PaperSize = PaperSize.A4 } 
};

// Send sheet via email.
smartsheet.SheetResources.SendSheet(sheetId, sheetEmail);
// Specify individual recipient.
RecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder().setEmail("john.doe@smartsheet.com").build();

// Specify group recipient.
RecipientGroup recipientGroup = new RecipientGroup.AddRecipientGroupBuilder().setGroupId(2258118617917316).build();

// Set recipients.
List<Recipient> recipients = Arrays.asList(recipientEmail, recipientGroup);

// Set format details.
FormatDetails formatDetails = new FormatDetails();
formatDetails.setPaperSize(PaperSize.A0); 

// Configure email.
SheetEmail email = new SheetEmail.AddSheetEmailBuilder()
    .setSendTo(recipients)
    .setSubject("Check these rows out!")
    .setMessage("Here are the rows I mentioned in our meeting")
    .setCcMe(false)
    .setFormat(SheetEmailFormat.PDF)
    .setFormatDetails(formatDetails)
    .build();

// Send sheet via email.
smartsheet.sheetResources().sendSheet(sheetId, email);
# Send sheet via email.
action = smartsheet.Sheets.sendSheet(
    sheetId,
    smartsheet.models.SheetEmail({
        'send_to': [
            smartsheet.models.Recipient({'email': 'john.doe@smartsheet.com'}),
            smartsheet.models.Recipient({'group_id': 2258118617917316})
        ],
        'subject': 'Check these rows out!',
        'message': 'Here are the rows I mentioned in our meeting.',
        'cc_me': False,
        'format': 'PDF',
        'format_details': smartsheet.models.FormatDetails({
            'paper_size': '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 ACCESS_TOKEN
Content-Type: application/json
Request Body SheetEmail object
Returns Result object

Send Update Request

Example Request:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '{ \
    "sendTo": [ \
        {"email": "recipient1@smartsheet.com"}, \
        {"email": "recipient2@smartsheet.com"} \
    ], \
    "subject": "some subject", \
    "message": "some message", \
    "ccMe": false, \
    "rowIds": [4508292249610116, 2256492435924868], \
    "columnIds": [4508284196546436, 2256484382861188], \
    "includeAttachments": false, \
    "includeDiscussions": false \
}'
// [todo]
// [todo]
# [todo]

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:

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests \
-H "Authorization: Bearer ACCESS_TOKEN" \
-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 ACCESS_TOKEN
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 will be 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 (i.e., not the primary email address associated with the User account), the Error object returned will contain 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”
      }
  ]
}

Server Information

For developer convenience, the Smartsheet API provides access to application constants.

Objects

ServerInfo Object

supportedLocales array Array of strings representing all Smartsheet-supported locales.
formats FormatTables Definition of format tables that are used in Column, Row, and Cell format property. For more information, see Formatting.

Get Server Info

Example Request:

curl https://api.smartsheet.com/2.0/serverinfo
// Get server info.
smartsheet.server.getInfo()
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Get server info.
smartsheet.ServerInfoResources.GetServerInfo();
// Get server info.
smartsheet.serverInfoResources().getServerInfo();
# Get server info.
info = smartsheet.Server.server_info()

Example Response: (too long to list in its entirety)

{
        "supportedLocales": [  ],
        "formats": {  }
}

GET /serverinfo

Gets application constants.

Access Scope None required (may be called unauthenticated)
Headers None required (may be called unauthenticated)
Returns ServerInfo object

Sharing

Use the Sharing operations to control sharing of Reports, Sheets, Workspaces, and Sights.

Objects

Share Object

id number Share ID.
NOTE: unlike other Smartsheet object ids, this id is an alphanumeric string.
type string The type of this share. One of the following values: USER or GROUP.
userId number User ID if the share is a user share, else null.
groupId number Group ID if the share is a group share, else null.
email string User’s primary email address for user shares; null for group shares.
name string If a user share and user is also a contact, the user’s full name. If a group share, the group’s name.
accessLevel string User or group’s access level on shared object.
scope string The scope of this share. One of the following values:
  • ITEM: an item-level share (i.e., the specific object to which the Share applies is shared with the user or group)
  • WORKSPACE: a workspace-level share (i.e., the workspace that contains the object to which the Share applies is shared with the user or group)
createdAt timestamp Time that the share was created.
modifiedAt timestamp Time that the share was modified.
subject string The subject of the email that will optionally be sent to notify the recipient. This attribute can be specified in a request, but will never be present in a response.
message string The message to be included in the body of the email that will optionally be sent to the recipient. This attribute can be specified in a request, but will never be present in a response.
ccMe boolean Flag to indicate whether or not to send a copy of the email to the sharer of the sheet. This attribute can be specified in a request, but will never be present in a response.

Sights Sharing

Delete Sight Share

Example Request:

curl https://api.smartsheet.com/2.0/sights/{sightId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// [todo]
// [todo]
// [todo]
# [todo]

Example Response:

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

DELETE /sights/{sightId}/shares/{shareId}

Deletes the Share specified in the URL.

Access Scope SHARE_SIGHTS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Sight Share

Example Request:

curl https://api.smartsheet.com/2.0/sights/{sightId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" 
// [todo]
// [todo]
// [todo]
# [todo]

Example Response:

{
    "id": "AQAISF82FOeE",
    "type": "GROUP",
    "groupId": 2331373580117892,
    "name": "Group 1",
    "accessLevel": "ADMIN",
    "scope": "ITEM",
    "createdAt": "2016-02-17T22:24:09Z",
    "modifiedAt": "2016-02-17T22:24:09Z"
}

GET /sights/{sightId}/shares/{shareId}

Gets the Share specified in the URL.

Access Scope READ_SIGHTS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Share object

List Sight Shares

Example Request:

curl https://api.smartsheet.com/2.0/sights/{sightId}/shares \
-H "Authorization: Bearer ACCESS_TOKEN" 
// [todo]
// [todo]
// [todo]
# [todo]

Example Response:

{
    "pageNumber": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 2,
    "data": [
        {
            "id": "AAAQSF82FOeE",
            "type": "USER",
            "userId": 4583173393803140,
            "email": "john.doe@smartsheet.com",
            "name": "John Doe",
            "accessLevel": "OWNER",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:24:09Z"
        },
        {
            "id": "AQAISF82FOeE",
            "type": "GROUP",
            "groupId": 2331373580117892,
            "name": "Group 1",
            "accessLevel": "ADMIN",
            "scope": "ITEM",
            "createdAt": "2016-02-17T22:24:09Z",
            "modifiedAt": "2016-02-17T22:25:08Z"
        }
    ]
}

GET /sights/{sightId}/shares

Gets a list of all Users and Groups to whom the specified Sight is shared, and their access level.

Access Scope READ_SIGHTS
Headers Authorization: Bearer ACCESS_TOKEN
Parameters include (optional): when specified with a value of workspaceShares, response will contain both item-level shares (scope='ITEM’) and workspace-level shares (scope='WORKSPACE’).

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 Share objects

NOTE: If the response contains an item-level share (scope='ITEM’) and a workspace-level share (scope='WORKSPACE’) for the same user or group, the id of those two Share objects will be identical, but the scope attribute value can be used to disambiguate the two.

Share Sight

Example Request:

curl https://api.smartsheet.com/2.0/sights/{sightId}/shares?sendEmail=true \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X POST \
-d '[{"email": "jane.doe@smartsheet.com", "accessLevel": "EDITOR"}]'
// [todo]
// [todo]
// [todo]
# [todo]

Example Response:

{
    "resultCode": 0,
    "result": [
        {
            "id": "AAAFeF82FOeE",
            "type": "USER",
            "userId": 1539725208119172,
            "email": "jane.doe@smartsheet.com",
            "name": "Jane Doe",
            "accessLevel": "EDITOR",
            "scope": "ITEM"
        }
    ],
    "message": "SUCCESS"
}

POST /sights/{sightId}/shares

Shares a Sight with the specified Users and Groups.

If called with a single Share object, and that user or group share already exists, error code 1025 will be returned. If called with an array of Share objects, and one or more user or group shares in the array already exist, they will be ignored and omitted from the response.

Access Scope SHARE_SIGHTS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Parameters sendEmail (optional): Either true or false to indicate whether or not to notify the user by email. Default is false.
Request Body Share object or an array of Share objects, with the following attributes:
  • email (optional): the individual share recipient’s email address
  • groupId (optional): the group share recipient’s group ID
  • accessLevel (required)
  • subject (optional): The subject of the email that will optionally be sent to notify the recipient.
  • message (optional): The message to be included in the body of the email that will optionally be sent to the recipient.
  • ccMe (optional): Boolean flag to indicate whether or not to CC the user sharing the sheet.
NOTE: One of email or groupId must be specified, but not both.
Returns Result object containing either a single Share object or an array of Share objects, corresponding to what was specified in the request. All shares will have scope=“ITEM”.
Errors If an error occurs because the request specified one or more alternate email addresses (i.e., not the primary email address associated with the User account), the Error object returned will contain 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 Sight Share

Example Request:

curl https://api.smartsheet.com/2.0/sights/{sightId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-X PUT \
-d '{"accessLevel": "VIEWER"}'
// [todo]
// [todo]
// [todo]
# [todo]

Example Response:

{
    "resultCode": 0,
    "result": {
        "id": "AAAFeF82FOeE",
        "type": "USER",
        "userId": 1539725208119172,
        "email": "jane.doe@smartsheet.com",
        "name": "Jane Doe",
        "accessLevel": "VIEWER",
        "scope": "ITEM"
    },
    "message": "SUCCESS"
}

PUT /sights/{sightId}/shares/{shareId}

Updates the access level of a User or Group for the specified Sight.

Access Scope SHARE_SIGHTS
Headers Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Request Body Share object limited to the following attribute:
  • accessLevel (string)
Returns Result object containing the modified Share object

Report Sharing

Delete Report Share

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
// Set options.
var options = {
    reportId: 665829219035012,
    shareId: "AAAQSF82F1eE"
};

// Delete report share.
smartsheet.reports.deleteShare(options)
    .then(function (data) {
        console.log(data);
    })
    .catch(function (error) {
        console.log(error);
    });
// Delete report share.
smartsheet.ReportResources.ShareResources.DeleteShare(reportId, shareId);
// Delete report share.
smartsheet.reportResources().shareResources().deleteShare(reportId, shareId);
# Delete report share.
smartsheet.Reports.delete_share(reportId, shareId)

Example Response:

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

DELETE /reports/{reportId}/shares/{shareId}

Deletes the Share specified in the URL.

Access Scope SHARE_SHEETS
Headers Authorization: Bearer ACCESS_TOKEN
Returns Result object

Get Report Share

Example Request:

curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId} \
-H "Authorization: Bearer ACCESS_TOKEN" 
// Set options.
var options = {
    reportId: 6932724448552836,
    shareId: "AQAISF82FOeE"
};

// Get report share.
smartsheet.reports.getShare(options)
    .then