Smartsheet API 2.0 allows you to programmatically access and manage your organization's Smartsheet data and account information. The API allows you to do the following:
Once you scroll to the Developer Reference section, you can view code examples in the programming language of your choice by clicking the corresponding tab in the rightmost pane. Each tab corresponds to a Software Development Kit (SDK) that Smartsheet provides to make working in that programming language easier. See SDKs and Sample Code.
NOTE: for the introduction, the rightmost pane is blank. Code samples are visible there at the endpoint level.
If you have feedback on the documentation, you can reach us using the Smartsheet Community API Category.
Allows an admin to act on behalf of, or impersonate, the user to make API calls. You might do this to troubleshoot a user problem or cover for vacations and sick time. As with cURL, the email address used to identify the user must be URI-encoded.
An admin cannot impersonate another admin.
NOTE: You must manually generate a token to assume user.
The Smartsheet API uses OAuth 2.0 for authentication and authorization. An HTTP header containing an access token is required to authenticate each request.
WARNING: If an unauthorized user gets a copy of this token, they will be able to access all Smartsheet data that you have access to, both to read and modify on your behalf. You should keep your tokens secure and do not share them with anyone. See Security for best practices.
The Smartsheet API returns all dates and times in the UTC time zone in ISO-8601 format, that is, YYYY-MM-DDTHH:MM:SSZ. If you are specifying a date and time, you should also send that information in ISO-8601 format. If a date/time needs to be displayed to an end-user in their local time zone, you must do the conversion using the user's time zone, which you can obtain by getting the current user.
You can optionally choose to receive and send dates/times in numeric format, as milliseconds since the UNIX epoch (midnight on January 1, 1970 in UTC time), using the query string parameter numericDates with a value of true. This query parameter works for any API request.
NOTE: Some SDK methods use language-specific Date objects, which require different date formats.
You cannot create or update filters using the API; however, you can query which rows have been filtered out and you can get filter definitions.
For details, see Filters object.
To set or read formatting programmatically, Smartsheet uses a compact format string, cell.format, which looks something like this: ",,1,1,,,,,,,,,,,,,"
. The position and sample values in this string are explained in the following format descriptor table:
Format Descriptor Table
Position | Lookup Property | Example Value | Format String |
---|---|---|---|
0 | fontFamily | 0 = Arial, default | "0,,,,,,,,,,,,,,,," |
1 | fontSize | 0 = 10 pt, default | ",0,,,,,,,,,,,,,,," |
2 | bold | 1 = on | ",,1,,,,,,,,,,,,,," |
3 | italic | 1 = on | ",,,1,,,,,,,,,,,,," |
4 | underline | 1 = on | ",,,,1,,,,,,,,,,,," |
5 | strikethrough | 1 = on | ",,,,,1,,,,,,,,,,," |
6 | horizontalAlign | 2 = center | ",,,,,,2,,,,,,,,,," |
7 | verticalAlign | 2 = middle | ",,,,,,,2,,,,,,,,," |
8 | color (text) | 4 = #FEEEF0 | ",,,,,,,,4,,,,,,,," |
9 | color (background) | 8 = #E6F5FE | ",,,,,,,,,8,,,,,,," |
10 | color (taskbar) | 9 = #F3E5FA | ",,,,,,,,,,9,,,,,," |
11 | currency | 13 = USD | ",,,,,,,,,,,13,,,,," |
12 | decimalCount | 3 = three decimal places | ",,,,,,,,,,,,3,,,," |
13 | thousandsSeparator | 1 = on | ",,,,,,,,,,,,,1,,," |
14 | numberFormat | 2 = currency | ",,,,,,,,,,,,,,2,," |
15 | textWrap | 1 = on | ",,,,,,,,,,,,,,,1," |
16 | dateFormat | 1 = mmmm d yyyy (December 8, 1997) | ",,,,,,,,,,,,,,,,1" |
NOTES:
",,1,1,,,,,,,,,,,,,"
.GET /serverinfo
to return the FormatTables object, which tells you both the default settings and what formatting options are available.Applying Formatting
Use the "include=format" query-string parameter on API operations that return detailed objects, such as GET /sheets/{sheetId}
or GET sheets/{sheetId}/rows/{rowId}
. If there is formatting other than default settings, the return includes a format property. If an object has conditional formatting, the format property returned will have a conditionalFormat value.
Setting the format of a row object or column object through the API simply sets the baseline format for new or blank cells in that row or column. It does not affect cells that already have a value.
If you want to change the formatting of cells that already have content, for instance you want to make a row bold, then you have to set the format for each cell individually.
Formulas are processed per cell in the UI. Use the Cell object to manipulate formulas via the API.
For requests, use Update Rows to add or update the formula in a cell.
For response payloads, formulas (when present) are returned whenever the Cell object is returned, so for example, GET /sheets/(id) returns the Cell object for each cell and that object contains a formula value when the cell contains a formula.
The REST URL structure follows typical resource-oriented conventions.
To get a list of sheets, use the following:
GET https://api.smartsheet.com/2.0/sheets
This returns a list of Sheet objects, where each sheet has an id attribute.
To get details on the sheet with id 123456, use the following:
GET https://api.smartsheet.com/2.0/sheets/123456
This Id pattern is repeated throughout the API. Columns, rows, cells, comments, attachments, or any other data element have a unique Id.
If you don't want to make raw HTTP calls, Smartsheet also has several Software Development Kits (SDKs) that provide a higher level interface for popular programming languages. For more information, see SDKs and Sample Code.
Unless otherwise specified, all API endpoints expect request body data to be in JSON, and the response body data is returned as JSON.
The following HTTP request headers may be required, depending on the operation and endpoint being invoked:
Header | Definition | Example |
---|---|---|
Authorization | Required for all endpoints, except for POST /token . The access token. |
Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | Required for POST and PUT requests. Defines the structure for the response. | application/json |
Assume-User | Optional. Allows an admin to act on behalf of, or impersonate, the user to make API calls. The email address used to identify the user must be URI-encoded. | jane.doe%40smartsheet.com |
Call the API using the following standard HTTP methods:
Smartsheet uses a combination of HTTP status codes and custom error codes with a descriptive message in JSON-formatted Error objects to give you a more complete picture of what has happened with your request.
HTTP status code |
Meaning | To Retry or Not to Retry? |
---|---|---|
2xx | Request was successful. Example: 200 Success |
-- |
4xx | A problem with request prevented it from executing successfully. | Never automatically retry the request. If the error code indicates a problem that can be fixed, fix the problem and retry the request. |
5xx | The request was properly formatted, but the operation failed on Smartsheet's end. | In some scenarios, requests should be automatically retried using exponential backoff. |
For example, doing a GET
on a non-existent sheet at https://api.smartsheet.com/2.0/sheets/123456
results in an HTTP status code of 404, indicating the resource was not found.
{
"errorCode": 1006,
"message": "Not Found"
}
Some errors may contain a detail attribute set to an object with additional error details that may be useful in programmatically handling the error. If so, it is noted in the specific API operation for which the error may occur.
NOTE: Smartsheet has custom error codes to help you troubleshoot issues. See the complete Error Code List.
New column types, such as MULTI_CONTACT_LIST and MULTI_PICKLIST, offer more complex ways to work with columns. Smartsheet has provided a backwards compatible way for these payloads to work with your existing integrations while also giving you a way to query for their content.
With either column type, there are two ways of receiving the response:
Smartsheet uses two indicators to help you discover changes in the return data for your API calls:
Text | Multi-contact | Multi-picklist |
---|---|---|
0 | 1 | 2 |
You must use the level query parameter, for example level=2, to return a complex object with the new column type. Without the query parameter, the response will be backwards-compatible, that is a string.
Use the highest possible level for each endpoint, as in the following table:
Endpoint category | Level |
---|---|
Dashboards | 4 |
Reports | 3 |
Sheets | 2 |
NOTE: The include=objectValue query parameter is necessary to see the return as a complex value, such as actual email addresses rather than display names.
Many of the List All commands, for example, GET /sheets
, return only an abbreviated object for each object returned. For full details, read a single item, such as GET /sheets/{sheetId}
. In many cases, you can refine the exact object properties to be returned by using include and exclude query parameters.
The JSON representation of the objects returned from the List All REST endpoints will only include a subset of the properties documented here. However, the objects returned from the Java and C# SDKs will represent the omitted properties with NULLs.
Many API calls can be modified by including one or more of these common query strings:
Query Parameter | Type | Description | More Info |
---|---|---|---|
accessApiLevel | Number | Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessAPILevel=1. | |
allowPartialSuccess | Boolean | If true, allows bulk operations to process even if one or more operations are invalid for some reason, for example, allowPartialSuccess=true. | Bulk Operations |
include or exclude | String | When applicable for a specific object, various include or exclude parameters are available, for example, include=format. | Object reference or Formatting |
includeAll | Boolean | If true, includes all results, for example, includeAll=true. | Paging |
numericDates | Boolean | If true, allows you to input or receive dates in numeric format, for example, numericDates=true. | Dates and Times |
page | String | Specifies which page to return, for example, page=4. | Paging |
pageSize | Number | Specifies the maximum number of items to return per page, for example, pageSize=25. | Paging |
NOTE: Query strings are case sensitive. If you do not see the expected response, confirm that your query is formatted correctly.
If you want to get started quickly, or are developing a standalone application that can run with your credentials, follow these instructions:
The access token must be sent with every API call in an HTTP authorization header (except for the requests to Get Access Token or Refresh Access Token). Once you have an access token, include it in the Authorization header for every request you make:
Authorization: Bearer ll352u9jujauoqz4gstvsae05
The header name is Authorization and the value of the header is Bearer ll352u9jujauoqz4gstvsae05. Since the access token is being transmitted in clear text, all API calls are done over HTTPS.
NOTE: A best practice is to use a shared account, such as ticket-processor@example.com, rather than your individual work account.
Smartsheet has Software Development Kits (SDKs) providing a higher level interface for several languages.
Language | SDK | Sample application |
---|---|---|
C# | smartsheet-csharp-sdk | csharp-read-write-sheet |
Java | smartsheet-java-sdk | java-read-write-sheet |
Node.js | smartsheet-javascript-sdk | node-read-write-sheet |
Python | smartsheet-python-sdk | python-read-write-sheet |
Ruby | smartsheet-ruby-sdk | ruby-read-write-sheet |
In addition to the sample application provided for each SDK, you can always view code examples in this document by clicking the corresponding tab in the dark-blue area in the rightmost pane.
To use an SDK for development work, follow the instructions in the SDK readme to download and install the SDK. Then download the sample app and run it. Once you've run the sample application, you can clone it and use the structure it provides to start building your own applications.
Sheets are composed of rows, columns, and cells. A cell is identified by the Id of its row and column. The following table defines these terms and points you to places in this documentation where you can find more information:
UI Element | Description | More Info |
---|---|---|
sheet | A sheet can exist in a user's Home folder, in a folder, or in a workspace. It is comprised of columns, rows, and cells, and may optionally contain attachments or discussions. | Sheet object |
column | A Column object defines the type of the column, but does not actually contain cells. The Column Id identifies the cells in a row. | Column object, Column types |
row | A row is a component of a sheet or report. Each row is composed of a collection of cells, and may optionally contain attachments or discussions. | Row object |
cell | A cell is a location within a sheet that may contain a value. A collection of cells comprises each row in a sheet. | Cell object, Cell reference |
Smartsheet will add new functionality and bug fixes to the API over time. Make sure that your code can handle new JSON properties gracefully. Also, make sure your code does not depend on the order in which JSON objects are returned, unless it is explicitly stated in this documentation.
When there is new functionality that is not compatible with existing code, say in the case of a new concept, Smartsheet increments the level to indicate the new feature can be ignored until you are ready to implement the code to work with the new level.
See also: Multi-contact or Multi-picklist: Working with Complex Objects
Before you write any code, try executing API requests using a tool like cURL or Postman. By taking your code out of the equation, you can isolate troubleshooting to the raw request and response.
You must use an access token. See instructions at Authentication and Access Tokens. In the examples below, replace this sample token, "ll352u9jujauoqz4gstvsae05", with your actual token value.
WARNING: If an unauthorized user gets a copy of this token, they will be able to access all Smartsheet data that you have access to, both to read and modify on your behalf. You should keep your tokens secure and do not share them with anyone. See Security for best practices.
To get a list of all your sheets, try the following command:
curl -X GET -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" "https://api.smartsheet.com/2.0/sheets"
In Postman, the request looks like this:
The JSON result should look something like this (after formatting):
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [{
"id": 6141831453927300,
"name": "My first sheet",
"accessLevel": "ADMIN",
"permalink": "https://app.smartsheet.com/b/home?lx=8enlO7GkdYSz-cHHVus33A",
"createdAt": "2016-01-28T22:02:35Z",
"modifiedAt": "2016-08-09T17:50:06Z"
},
{
"id": 6141831453927300,
"name": "Sheet shared to me",
"accessLevel": "VIEWER",
"permalink": "https://app.smartsheet.com/b/home?lx=8enlO7GkdYSz-cHHVus33A",
"createdAt": "2016-01-28T22:02:35Z",
"modifiedAt": "2016-08-09T17:50:06Z"
}
]
}
Many Smartsheet API operations handle sheets, rows, columns, and cells. Each is identified by an Id and it is important to understand the relationship between these objects. Typically you loop through the columns to determine the Id of the columns you are interested in. Then you loop through the rows and contained cells to find actual values. The annotated sample response below illustrates these concepts by calling a very simple sheet called "Employee Roster".
Before you begin, you should already have an access token, which you used in the exercise above. Use the same access token for this walkthrough.
Step 1: The first thing you must have is a sheetId. To find a sheetId through the UI, with the sheet open, click "Sheet Actions" in the left toolbar and select "Properties". NOTE: use List Sheets if you want to do this programmatically.
Step 2: Copy the sheetId into the API call, GET /sheets
, as below:
curl -X GET -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" "https://api.smartsheet.com/2.0/sheets/6141831453927300"
Step 3: The sample request and response are displayed below. NOTE: while JSON doesn't have a comment feature, this sample uses comments to help you identify the objects in the response.
{
"id": 6141831453927300, // Sheet Id
"name": "My first sheet",
"columns": [{ // Each Column object associates column Id
// to title and defines the
// column details
"id": 2517104256673668, // Column Id
"index": 0,
"title": "Name",
"type": "TEXT_NUMBER",
"primary": true,
"width": 150
},
{
"id": 7020703884044164, // Next column Id
"index": 1,
"title": "EmployeeId",
"type": "TEXT_NUMBER",
"width": 150
}
],
"rows": [{ // A Row object
"id": 564480076736388, // Row Id
"rowNumber": 1,
"expanded": true,
"createdAt": "2017-05-12T16:52:38Z",
"modifiedAt": "2017-05-22T20:40:14Z",
"cells": [{ // Each row contains an array of cells,
// which have the actual content
"columnId": 2517104256673668,
// The column Id can be interpreted by
// looking at the array of column
// definitions above. That tells you
// this is the "Name" column
"value": "John Doe",
"displayValue": "John Doe"
},
{
"columnId": 7020703884044164,
"value": 12345, // Actual cell value
"displayValue": "12,345"
// How the cell value is displayed in the UI
}
]},
{
"id": 5068079704106884,
"rowNumber": 2,
"siblingId": 564480076736388,
"expanded": true,
"createdAt": "2017-05-12T16:52:38Z",
"modifiedAt": "2017-05-22T20:40:14Z",
"cells": [{
"columnId": 2517104256673668,
"value": "Jane Roe",
"displayValue": "Jane Roe"
},
{
"columnId": 7020703884044164,
"value": 67890,
"displayValue": "67890"
}
]
}
]
}
This core hierarchy of Sheet > Column > Row > Cell is essential to working with the Smartsheet API. As your user's sheets grow in complexity, the responses do too. This walkthrough has given you some navigational aid in finding the right value to plug into your API calls. Use the API Reference and the example language tabs to learn more.
For an explanation of the logic behind Smartsheet error codes and error handling, see the HTTP and REST portion of the Introduction.
400-level error codes generally indicate that there is something you should fix or add to your request before you try the request again.
HTTP status code | Smartsheet errorCode | Smartsheet message |
---|---|---|
401 | 1001 | An Access Token is required. |
401 | 1002 | Your Access Token is invalid. |
401 | 1003 | Your Access Token has expired. |
403 | 1004 | You are not authorized to perform this action. |
401 | 1005 | Single Sign-On is required for this account. |
404 | 1006 | Not Found. |
404 | 1007 | Version not supported. |
400 | 1008 | Unable to parse request. The following error occurred: {0} |
400 | 1009 | A required parameter is missing from your request: {0}. |
405 | 1010 | HTTP Method not supported. |
400 | 1011 | A required header was missing or invalid: {0} |
400 | 1012 | A required object attribute is missing from your request: {0}. |
403 | 1013 | The operation you are attempting to perform is not supported by your plan. |
403 | 1014 | There are no licenses available on your account. |
403 | 1015 | The user exists in another account. The user must be removed from that account before they can be added to yours. |
403 | 1016 | The user is already a member of your account. |
403 | 1017 | The user already has a paid account. The user must cancel that account before they can be added to yours. |
400 | 1018 | The value {0} was not valid for the parameter {1}. |
400 | 1019 | Cannot transfer to the user specified. User not found. |
404 | 1020 | User not found. |
403 | 1021 | Cannot transfer to the user specified. They are not a member of your account. |
403 | 1022 | Cannot delete the user specified. They are not a member of your account. |
400 | 1023 | The sheet specified is shared at the Workspace level. |
400 | 1024 | The HTTP request body is required for this Method. |
400 | 1025 | The share already exists. |
403 | 1026 | Transferring ownership is not currently supported. |
404 | 1027 | Share not found. |
400 | 1028 | You cannot edit the share of the owner. |
400 | 1029 | The parameter in the URI does not match the object in the request body. |
401 | 1030 | You are unable to assume the user specified. |
400 | 1031 | The value {0} was not valid for the attribute {1}. |
400 | 1032 | The attribute(s) {0} are not allowed for this operation. |
404 | 1033 | The template was not found. |
400 | 1034 | Invalid Row Id. |
400 | 1035 | Deprecated. |
400 | 1036 | The columnId {0} is invalid. |
400 | 1037 | The columnId {0} is included more than once in a single row. |
400 | 1038 | Invalid Cell value. Must be numeric or a string. |
403 | 1039 | Cannot edit a locked column {0}. |
400 | 1040 | Cannot edit your own share. |
400 | 1041 | The value for {0} must be {1} characters in length or less, but was {2}. |
400 | 1042 | The value for cell in column {0}, {1}, did not conform to the strict requirements for type {2}. |
404 | 1043 | The row number you requested is blank and cannot be retrieved. |
400 | 1044 | Assume-User header is required for your Access Token. |
403 | 1045 | The resource specified is read-only. |
400 | 1046 | Cells containing system values cannot be inserted or updated through the API, columnId : {0}. |
403 | 1047 | You cannot remove yourself from the account through the API. |
403 | 1048 | The user specified has declined the invitation to join your organization. You cannot modify declined invitations. |
403 | 1049 | You cannot remove admin permissions from yourself through the API. |
403 | 1050 | You cannot edit a locked row. |
400 | 1051 | Attachments of type FILE cannot be created using JSON. |
406 | 1052 | Invalid Accept header. Media type not supported. |
400 | 1053 | Unknown Paper size: {0}. |
400 | 1054 | The new sheet requires either a fromId or columns. |
400 | 1055 | One and only one column must be primary. |
400 | 1056 | Column titles must be unique. |
400 | 1057 | Primary columns must be of type TEXT_NUMBER. |
400 | 1058 | Column type of {1} does not support symbol of type {0}. |
400 | 1059 | Column options are not allowed when a symbol is specified. |
400 | 1060 | Column options are not allowed for column type {0}. |
400 | 1061 | Max count exceeded for field {0}. |
400 | 1062 | Invalid row location. |
400 | 1063 | Invalid parentId: {0}. |
400 | 1064 | Invalid siblingId: {0}. |
400 | 1065 | The column specified cannot be deleted. |
400 | 1066 | You can only share to {0} users at a time. |
401 | 1067 | Invalid client_id |
400 | 1068 | Unsupported grant type. |
400 | 1069 | Invalid Request. The authorization_code has expired. |
400 | 1070 | Invalid Request. Required parameter is missing: {0}. |
400 | 1071 | Invalid Grant. The authorization code or refresh token provided was invalid. |
400 | 1072 | Invalid hash value. The hash provided did not match the expected value. |
400 | 1073 | The redirect_uri did not match the expected value. |
400 | 1074 | You are trying to upload a file of {0}, but the API currently only supports {1}. |
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. |
403 | 1076 | The user has created sheets and must be added as a licensed user. |
400 | 1077 | Duplicate system column type: {0}. |
400 | 1078 | System column type {0} not supported for {1} {2}. |
400 | 1079 | Column type {0} is not supported for system column type {1}. |
400 | 1080 | End Dates on dependency-enabled sheets cannot be created/updated. Please update either the Duration or Start Date column. |
403 | 1081 | You cannot delete or update another user's discussions, comments, or comment attachments. |
400 | 1082 | You cannot add options to the given column {0} because it is not a PICKLIST. |
400 | 1083 | Auto number formatting cannot be added to a column {0}. |
400 | 1084 | The auto number format is invalid. |
400 | 1085 | To change this column's type you must first disable Dependencies for this sheet. |
400 | 1086 | Google was not able to verify your access. |
400 | 1087 | The column specified is used in a conditional formatting rule, so the column cannot be deleted and its type cannot be changed. |
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. |
400 | 1089 | The type specified is only used with System Columns. |
400 | 1090 | Column.type is required when changing symbol, systemColumnType or options. |
400 | 1091 | Invalid Content-Type: {0}. |
403 | 1092 | You cannot delete this row. Either it or one or more of its children are locked. |
400 | 1093 | Apple verification not available. |
400 | 1094 | Can't set password without licensed account. |
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. |
403 | 1096 | This Apple payment receipt has already been applied to a user's payment profile. |
403 | 1097 | A user must be a licensed sheet creator to be a resource viewer. |
400 | 1098 | To delete this column you must first disable Dependencies for this sheet. |
400 | 1099 | To delete this column you must first disable Resource Management for this sheet. |
400 | 1100 | Uploading new versions of a discussion comment attachment is not supported. |
400 | 1101 | Uploading new versions of non-FILE type attachments is not supported. |
403 | 1102 | A user must be a licensed sheet creator to be a group administrator. |
400 | 1103 | A group with the same name already exists. |
403 | 1104 | You must be a group administrator to create a group. |
400 | 1105 | The operation failed because one or more group members were not members of your account: {0}. |
404 | 1106 | Group not found. |
400 | 1107 | User specified in transferGroupsTo must be a group admin. |
400 | 1108 | transferGroupsTo must be provided because user being deleted owns one or more groups. |
400 | 1109 | Only one of cell.hyperlink or cell.linkInFromCell may be non-null. |
400 | 1110 | cell.value must be null if cell.linkInFromCell is non-null. |
400 | 1111 | Only one of cell.hyperlink.sheetId and cell.hyperlink.reportId may be non-null. |
400 | 1112 | cell.hyperlink.url must be null for sheet or report hyperlinks. |
400 | 1113 | cell.value must be a string when the cell is a hyperlink. |
404 | 1114 | Invalid sheetId or reportId: {0}. |
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. |
400 | 1116 | You cannot link a cell to its own sheet. |
400 | 1117 | One of the following cell.hyperlink fields must be non-null: url, sheetId, or reportId. |
400 | 1118 | You cannot set the value of a Gantt allocation column (id {0}) in a row that has child rows. |
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. |
400 | 1121 | transferTo must be provided because user being deleted owns one or more groups. |
405 | 1122 | Requested URL does not support this method: {0}. |
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). |
415 | 1124 | Invalid Content-Type header. Media type not supported. |
400 | 1125 | Each part in a multipart payload must have a name. |
400 | 1126 | Multipart payload contained duplicate part names: {0}. |
400 | 1127 | Required multipart part was missing: '{0}' |
400 | 1128 | Multipart upload size limit exceeded. |
400 | 1129 | The resource you tried to create already exists. |
400 | 1130 | One of cell.value or objectValue may be set, but not both. |
400 | 1131 | cell.{0} for column {1} was of the wrong object type. Allowed types: {2}. |
400 | 1132 | The token provided has previously been revoked. |
400 | 1133 | Column titles are not unique among input columns. |
400 | 1134 | Duplicate system column type among input columns. |
400 | 1135 | Input column index {0} is different from the first input column index {1}. |
400 | 1136 | Cannot copy or move row(s) within the same sheet. |
400 | 1137 | Input collection contains multiple instances of the same element. |
403 | 1138 | The user is not eligible for a trial organization. |
403 | 1139 | The user is an admin in another organization. Add 'allowInviteAccountAdmin=true' to the query string to invite their entire organization. |
403 | 1140 | The user must be added as a licensed user. |
403 | 1141 | Inviting users from an enterprise organization is not supported. |
400 | 1142 | Column type {0} is reserved for project sheets and may not be manually set on a column. |
400 | 1143 | To set {0}, you must first enable dependencies on the sheet. |
400 | 1144 | The user owns one or more groups and must be added as a Group Admin. |
400 | 1145 | Multipart upload request was invalid. Please check your request headers and payload. |
400 | 1146 | Unsupported operation: {0}. |
400 | 1147 | Multipart request contained an invalid part name: '{0}' |
400 | 1148 | Numeric cell values must be between {0} and {1}. |
400 | 1149 | Not configured for Gantt. |
400 | 1150 | Invalide operation for shared. |
404 | 1151 | Scope object not found. |
400 | 1152 | URL must have HTTPS. |
403 | 1153 | Webhook app revoked. |
403 | 1154 | Webhook disabled by Smartsheet. |
400 | 1155 | You cannot set the '{0}' attribute for a cell in a 'Project Settings' column of a dependency-enabled sheet. |
400 | 1156 | Invalid email. |
400 | 1157 | This address is already associated with another Smartsheet account, so it cannot be added as an alternate address for this account. |
400 | 1158 | This address has not been confirmed yet, so it can't be set as the primary email address. |
400 | 1159 | The specified email address ({0}) is an alternate email address for a user with a primary email address of {1}. |
400 | 1160 | Invalid bulk request. See detail for more information. |
400 | 1161 | Cannot set altText for a cell that does not contain an image: row {0}, column {1}. |
400 | 1163 | If cell.image is non-null then value, objectValue, hyperlink, and linkInFromCell must all be null. |
400 | 1164 | Cannot add image to cell because this feature has been disabled by the org administrator. |
400 | 1165 | Cannot add image to cell with alt text larger than 100 characters. |
400 | 1166 | You cannot share Sights as an Editor. |
400 | 1167 | The resource you are attempting to access has expired. |
403 | 1173 | You must be in a Team/Enterprise account to specify a {0} value of '{1}'. |
403 | 1174 | The value for {0} is invalid because this publish option is configured to be restricted to users in this account. |
403 | 1175 | One or more publish options which you attempted to enable are disabled for this account. |
400 | 1176 | Array attribute(s) may not contain null elements: {0}. |
400 | 1177 | Arrays may not contain null elements. |
400 | 1178 | The following combination of attributes is not allowed for this operation: {0}. |
400 | 1179 | The schedule specified is invalid because endAt is earlier than the next send date. |
403 | 1180 | We are unable to process this request because the email has been associated with a different Smartsheet account. |
403 | 1181 | Only admins can edit shared filters. |
400 | 1182 | The specified sheet filter {0} does not exist for sheet {1}. |
400 | 1183 | Sheet filters must define at least one detail entry. |
400 | 1184 | Sheet {0} already has a filter named '{1}' of type {2}. |
400 | 1185 | Cannot create a child of a parent row that has no data in it. |
403 | 1186 | User's primary email address must be a validated domain. |
403 | 1187 | User's alternate address selected to be made primary must be a validated domain. |
403 | 1188 | The account status of the user specified is not active. |
400 | 1189 | Only Enterprise or Team accounts with security controls are able to change primary emails. |
400 | 1190 | Only Enterprise or Team accounts with special permission granted are able to change primary emails. |
400 | 1191 | Summary field attribute is the wrong type. |
403 | 1192 | Can't edit locked summary field. |
400 | 1193 | Duplicate summary field title. |
400 | 1194 | Invalid summary field type for options. |
400 | 1195 | Duplicate summary field index. |
400 | 1196 | Summary field type required for change. |
400 | 1197 | Summary field options not allowed for symbols. |
400 | 1198 | Unsupported symbol for summary field type. |
400 | 1199 | Maximum number summary fields exceeded. |
400 | 1200 | Duplicate summary field Id. |
400 | 1201 | Summary field image only. |
400 | 1202 | Summary field hyperlink value must be string. |
400 | 1203 | Can't link summary field to same sheet. |
404 | 1204 | Invalid sheet report dashboard Id. |
400 | 1205 | Can't set summary field alt text. |
400 | 1206 | Unsupported summary field format type. |
400 | 1207 | Attribute value is empty. |
400 | 1208 | Duplicate summary field title in request. |
400 | 1209 | Can't set attribute on column type. |
400 | 1210 | Column validation is not supported for column type '{0}'. |
400 | 1211 | Not authorized. |
403 | 1212 | You must be a sheet admin to override validation. |
400 | 1213 | Deprecated. |
400 | 1214 | Invalid notification level '{0}'. |
400 | 1215 | Notification not supported by level. |
400 | 1216 | Notification rule not found. |
400 | 1217 | Exceeds allowed max date. |
400 | 1218 | The attributes recipientColumnIds, recipients and notifyAllSharedUsers are mutually exclusive. Only one may be set, not all. |
400 | 1218 | The attributes includeAllColumnIds and includedColumnIds are mutually exclusive. Only one may be set not all. |
400 | 1219 | The attributes {0} and {1} are mutually exclusive. Only one may be set. |
400 | 1220 | Automation action type cannot be changed. |
400 | 1221 | The value {0} is not valid for the attribute action.recipientColumnIds. Only Contact List columns may be used. |
400 | 1222 | Invalid attribute for operation. |
400 | 1223 | Sort sheet with locked row. |
400 | 1224 | Invalid parameter value. |
400 | 1225 | Problem processing row header. |
400 | 1226 | Personal workspace not found. |
400 | 1227 | The query parameters '{0}' and '{1}' are mutually exclusive. Only one may be set. |
400 | 1228 | You must specify one of the following query parameters: '{0}' or '{1}'. |
400 | 1229 | The value '{0}' was not valid for the parameter '{1}'. The value must be between '{2}' and '{3}'. |
400 | 1230 | Duplicate bot type. |
400 | 1231 | Invalid bot type. |
403 | 1232 | Bot not enabled. |
400 | 1233 | Required form field missing. |
400 | 1234 | Form data empty. |
400 | 1235 | Value not supported on column. |
400 | 1236 | OAuth missing client auth. |
400 | 1237 | OAuth redundant client auth. |
400 | 1238 | OAuth invalid secret. |
400 | 1239 | Client column version mismatch. |
400 | 1240 | Multi-contact list limit. |
400 | 1241 | Invalid mulcit-contact name. |
400 | 1242 | Too many display column Ids. |
400 | 1243 | Invalid view by Id. |
400 | 1244 | Uncardable view by Id. |
400 | 1245 | Invalid display column Id. |
400 | 1246 | Displaying primary column in card view. |
400 | 1247 | Card view level below minimum. |
400 | 1248 | Invalid subtask column Id. |
400 | 1249 | Uncheckable subtask column Id. |
400 | 1250 | Card view not configured. |
400 | 1251 | Duplicate display column Id. |
400 | 1252 | Inconsistent lane values. |
400 | 1253 | Move card adjacent to self. |
400 | 1254 | Invalid view by Id for card operation. |
400 | 1255 | Attachment type '{0}' is not supported. |
400 | 1256 | Individual accounts disabled. |
400 | 1257 | Form hyperlink is not URL. |
400 | 1258 | Cannot move folder under descendant. |
400 | 1259 | Uncardable view by Id for card operation. |
400 | 1260 | Cannot delete last visible column. |
400 | 1261 | Uncardable column for editing lanes. |
400 | 1262 | Invalid card lane name. |
400 | 1263 | Duplicate card lane name. |
400 | 1264 | Column fields not allowed for editing lanes. |
400 | 1265 | Card view was never configured for lanes. |
400 | 1266 | This rule is not accessible through the API. Only single-action notifications, approval requests, or update requests qualify. |
400 | 1267 | Web content widget disabled. |
400 | 1268 | Dashboard web content widget custom domain URL disabled. |
403 | 1269 | Removing group admin who owns groups. |
403 | 1270 | Forbidden impersonate object owner. |
403 | 1271 | Forbidden impersonate user. |
400 | 1272 | Invalid impersonate header value. |
400 | 1273 | Both impersonate and assume user provided. |
400 | 1274 | Impersonate object owner not supported. |
403 | 1275 | Impersonate feature not enabled. |
400 | 1276 | Column type not supported. |
400 | 1277 | Multi-picklist invalid size. |
400 | 1279 | Proofing setting error. |
400 | 1280 | Proofing duplicate record. |
400 | 1281 | Proofing invalid file extension. |
400 | 1282 | Invalid JSON. |
400 | 1283 | Unrecognized JSON property. |
400 | 1284 | Dashboard level below minimum. |
400 | 1286 | Proofing service row move invalid. |
403 | 1287 | Publish disabled by sheet sys admin. |
403 | 1288 | Sheet disabled by admin. |
400 | 1289 | Proofing cannot disable with proofs. |
403 | 1301 | No permissions for column formulas. |
400 | 1302 | Cannot edit column formula cells. |
400 | 1303 | Unsupported column type for column formulas. |
400 | 1305 | Cannot set column formula on project column. |
400 | 1310 | Column formula syntax not supported. |
400 | 1314 | Plan type cannot use column formulas. |
400 | 1318 | Cannot delete baseline columns. |
400 | 1319 | Cannot update values in baseline columns. |
400 | 1320 | Cannot change a baseline column type. |
400 | 1321 | Cannot put a column formula in a baseline column. |
400 | 1322 | Cannot remove column formula from baseline variance column. |
400 | 1332 | Images not allowed in baseline columns. |
429 | 4003 | Rate limit exceeded. |
410 | 4005 | API version retired. |
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. |
500-level error codes indicate there is some kind of permanent error.
HTTP status code | Smartsheet errorCode | Smartsheet message |
---|---|---|
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. |
500 | 1170 | The sheet referenced by this widget is unavailable or deleted. |
500 | 1171 | The report referenced by this widget is unavailable or deleted. |
500 | 1172 | The referenced cell is unavailable or deleted. |
500 | 1278 | Proofing service error. |
500 | 1285 | Dashboard source profile field missing. |
500 | 4000 | An unexpected error has occurred. Please contact api@smartsheet.com for assistance. |
503 | 4001 | Smartsheet.com is currently offline for system maintenance. Please check back again shortly. |
500 | 4002 | Server timeout exceeded. Request has failed. |
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. |
500 | 5151 | The action could not be completed because the following people are outside of the approved domain sharing list:[email address] |
500 | 5502 | You must have sheet admin permission to save a notification with recipients other than yourself. |
Before you can start using OAuth 2.0 with your app, Smartsheet needs the following information:
After you've worked through these steps, you'll be ready to implement the OAuth Flow.
*Review the Developer Program Agreement.
Your app must implement a 3-legged OAuth flow to retrieve an access token it can use to access Smartsheet data on behalf of an end user. The following diagram has an overview of the OAuth flow:
NOTE: App registration and OAuth flow require HTTPS.
To access a user's Smartsheet data, your application must explicitly ask the user for permission. You do this by using access scopes, which enable your app to communicate to the user what type of operations it is performing. Access scopes do not override existing access-level restrictions. For example, having the access scope of WRITE_SHEETS does not allow your app to update a sheet on which the user has VIEWER access level.
See access scopes for a complete list.
NOTE: Additional Info:
GET https://app.smartsheet.com/b/authorize
POST https://app.smartsheet.com/b/authorize
Initiates the process to get authorization from the user. Smartsheet will redirect this URL to display your app's consent page with an explanation of the data the app will need access to. This consent page is autogenerated by Smartsheet based on a combination of the information you registered for your app and the parameters you send with the request.
Value | Description |
---|---|
client_id | Required. The client Id you obtained when you registered your app. |
response_type | Required. Indicates whether the endpoint returns an authorization code. Must be set to "code". |
scope | Required. Space-delimited list of access scopes to which you are asking the user to grant access. NOTE: No access scopes are necessary if you simply need to validate that the user has a Smartsheet account. |
state | Optional. An arbitrary string of your choosing that is returned to your app; a successful roundtrip of this string helps ensure that your app initiated the request. |
You can view code examples by clicking the corresponding tab in the rightmost pane. The cURL example shows a GET
.
A correctly formatted Auth URL request looks like this: https://app.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE
NOTE: If the user has not yet logged into Smartsheet, the redirect will first take them to a login page, and then display the consent page.
At this point, the user can authorize your app to access their Smartsheet account, as in the following example:
After the user clicks "Allow" or "Deny", you'll receive a response from Smartsheet outlined in the next sections.
If the user clicks "Allow", Smartsheet redirects the user to the callback URL with the following parameters:
Value | Description |
---|---|
code | Authorization code required to obtain access token, such as 'sample6p9qisx6a'. |
expires_in | Number of milliseconds code is valid once issued; this is currently 599135 milliseconds, or approx. 10 minutes--you must obtain an access token within that time. |
state | The same value for state that you sent when you requested the authorization code. |
At this point, you should verify the state value matches what you sent to the user when you requested the authorization code. This helps you determine that the response came from the user and not a malicious script. If the values do not match, you should reject the response.
For other error conditions, see the list of OAuth Error Types.
If the user clicks "Deny", Smartsheet redirects the user to the callback URL with the following parameters:
Value | Description |
---|---|
error | "access_denied". |
state | The same value for state that you sent when you requested the authorization code. |
Once you’ve successfully obtained an authorization code, the next step is to exchange the code for an access token. (Remember, the authorization code expires after 599135 milliseconds.)
Access tokens expire after 604799 seconds, which is approx 7 days. Use the refresh token to obtain a new access token and a new refresh token. Once you obtain the new tokens, you must use them in place of the old ones, which are no longer valid.
To get or refresh an access token, see Refresh Access Token.
Value | Description |
---|---|
invalid_client | The client information is invalid. Ensure your client id is correct. |
invalid_grant | The authorization code or refresh token is invalid or expired or the hash value does not match the app secret and/or code. |
invalid_request | The request parameters are invalid or missing. |
invalid_scope | One or more of the requested access scopes is invalid. Please check the list of access scopes. |
unsupported_grant_type | grant_type must equal authorization_code or refresh_token. |
unsupported_response_type | response_type must be set to code. |
Please note the following resources:
The following provides some best practices to consider when working with the Smartsheet API and any API keys, tokens, or other sensitive information.
If your application requires users to be able to login with their own account, you must implement the full OAuth flow.
At a high level, this involves the following steps:
NOTE: When using OAuth, be sure to review the Access Scopes needed for your app and only request the necessary scopes.
Sheets, templates, and workspaces have an accessLevel attribute that describes the current user's access level to that object. This corresponds directly to the sharing and access controls of Smartsheet that are available through the Smartsheet UI.
The accessLevel attribute has one of the following values:
Value | Description |
---|---|
ADMIN | The user can edit and share the resource, and can alter the structure of the resource as well. |
EDITOR | The user can edit the resource, but cannot alter the structure of, delete, or share the resource. |
EDITOR_SHARE | The same as EDITOR, but with the ability to share the resource to other users. |
OWNER | The user has complete control over the resource. |
VIEWER | The user has read-only access to the resource. |
NOTE: Smartsheet also uses access scopes. Access levels describe the actual permissions a specific user has for a specific sheet or other resource. Access scopes describe the general categories of access requested by a third-party app.
If you've committed code to a repository before implementing these security best practices, here are some steps to resecure your API keys.
For raw tokens:
If using OAuth for an integration:
Never commit API keys to accessible version control systems like GitHub or BitBucket. Instead, you should:
If you have mistakenly deployed API keys to a publicly accessible location such as GitHub, then you should immediately revoke those API keys, revise your application to use a preferred method of key deployment, and then generate new keys.
If you need to store API keys in a database, consider the following protections:
NOTE: When using any Smartsheet SDK, you can use the environment variable of SMARTSHEET_ACCESS_TOKEN. If the access token is null on input to the client builder, the SDK will automatically pick up the value of that environment variable.
Smartsheet Gov has "FedRAMP Authorized" status as part of Federal Risk and Authorization Management Program (FedRAMP). As an API developer working on a Smartsheet Gov account, you should be aware of the following differences from the standard API:
If you use a Smartsheet SDK, you need to modify the standard config file to point to smartsheetgov.com. There are instructions specific to each SDK on how to modify the config file at the following locations:
Smartsheet Regions Europe is a separate data island. As an API developer working on a Smartsheet Regions Europe account, you should be aware of the following differences from the standard API:
If you use a Smartsheet SDK, you need to modify the standard config file to point to smartsheet.eu. There are instructions specific to each SDK on how to modify the config file at the following locations:
Should you encounter issues with the Smartsheet API while building an integration using a particular programming language, for example C#, Java, Node.js, Python, or Ruby, keep the following troubleshooting techniques in mind.
Try executing the same API Request using a tool like cURL or Postman. By taking your code out of the equation, you can isolate troubleshooting to the raw Request / Response.
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).
Check for capitalization errors. NOTE: URL endpoints are all lower case, while object properties and query parameters are camelCase.
The Smartsheet API supports a number of bulk operations that can operate on multiple objects. Unlike single-object operations, bulk operations allow you to create, update, or delete multiple objects in a single request. For example, if you want to update 10 rows within a sheet, do so using a single Update Rows request, rather than executing 10 separate requests - one for each row.
Optional Bulk Operations
Several endpoints support optional bulk POST
operations which exist alongside the standard single-object POST
. For these endpoints, you may pass in either a single object or an array of objects.
Depending on what was passed in, the Result object returned contains either a single object or an array. An example optional bulk operation is POST /favorites: you can
pass in a single Favorite object to create a single favorite, or an array of Favorite objects to create multiple favorites in a single request. Endpoints which support bulk operations are
noted as such in the API reference documentation.
NOTE: Most POST
operations fail when attempting to create a single object which already exists (for example, favorites, shares, group members). However, for the corresponding bulk operations, these endpoints do not
return an error if one or more items in the array already exist. Existing items are simply ignored, and the Result object returned omits them.
Partial Success
In general, the default behavior for bulk operations is to fail outright if any of the objects in the request are invalid for some reason. If successful, Smartsheet creates/updates/deletes all objects in the request; if not, no objects are changed.
However, there are some operations that support partial success, which means the operation still succeeds even if one or more of the objects in the request fails for some reason (for example, an object is invalid). Here is another example: if you want to update more than one row, you send more than one row object in your request. If a row object is invalid, that row update will fail, but the other row updates will succeed. Partial success is not the default mode for an operation and you must explicitly enable it by using a query string parameter. This is noted in the documentation for operations that support partial success.
When partial success is enabled, and one or more of the objects in the request fail to be added/updated/deleted, a standard Result object is returned, but with a message of 'PARTIAL_SUCCESS' (instead of 'SUCCESS'), and a resultCode of 3. Additionally, the object contains a failedItems attribute -- an array of BulkItemFailure objects that contains an item for each object in the request that failed to be added/updated/deleted.
The Smartsheet API contains a number of index endpoints (typically denoted in the documentation with titles beginning with "Get All" or "List") which return arrays of objects.
Examples include GET
/users, /sheets, /sheets/{sheetId}/columns, and many others. These endpoints all support pagination, meaning
you can retrieve paged subsets of results, enabling you to process potentially large result sets in smaller chunks.
Paging Query String Parameters
Index endpoints all support pagination via the following optional query string parameters:
Value | Type | Description |
---|---|---|
includeAll | Boolean | If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified). |
page | number | Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
pageSize | number | The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. |
NOTE: Most index endpoints default to a page size of 100 results. If you want all results at once, you must specify the includeAll=true query string parameter.
Paged Responses
Index endpoints all return paged responses via an IndexResult object, which provides paging metadata that can be used to navigate the full set of pages in the result set:
Value | Type | Description |
---|---|---|
data | array | An array of objects representing the current page of data in the result set. |
pageNumber | number | The current page in the full result set that the data array represents. NOTE: when a page number greater than totalPages is requested, the last page is instead returned. |
pageSize | number | The number of items in a page. Omitted if there is no limit to page size (and hence, all results are included). Unless otherwise specified, this defaults to 100 for most endpoints. |
totalCount | number | The total number of items in the full result set. |
totalPages | number | The total number of pages in the full result set. |
Handle "Rate limit exceeded" Error
To prevent abuse and undue stress on the Smartsheet servers, the API has a rate limiting feature (sometimes called throttling) that restricts users to 300 requests per minute per access token. Certain resource intensive operations, such as attaching a file and getting cell history, count as 10 requests. Smartsheet reserves the right to enforce this limit depending on the load on our systems.
If and when the limit is enforced, any requests that exceed this limit are rejected with an 429 HTTP status code, along with the following JSON response body:
{
"errorCode": 4003,
"message": "Rate limit exceeded."
}
Smartsheet recommends that you design your integration to gracefully handle this rate limit error. One way of doing that would be to have your integration sleep for 60 seconds when this error is encountered, and then subsequently retry the request. Alternatively, you might choose to implement exponential backoff (an error handling strategy whereby you periodically retry a failed request with progressively longer wait times between retries, until either the request succeeds or the certain number of retry attempts is reached).
Avoid Executing "Rapid Fire" Updates
If the only thing your integration does is execute an Update Rows request once every second for the same sheet, that would only amount to a total of 60 requests per minute -- well within rate limiting guidelines. However, updating the same object in such rapid succession could result in save errors that negatively impact both your integration as well as user experience within the Smartsheet app. To avoid this scenario, design your integration such that API requests are never executed with rapid-fire succession against the same Smartsheet object. For maximum efficiency, consider batching up changes and submitting them in a single request using a bulk operation (for example, Update Rows or Add Columns.
Execute Requests Serially
Executing multiple API requests in parallel to update a specific Smartsheet object results in reduced performance and often results in errors due to save collisions. To avoid this scenario, design your integration such that API requests to update a specific Smartsheet object are always executed serially (that is, execute one request at time, not beginning the next request until the previous request has completed).
NOTE: Attempts to perform multiple concurrent updates to a sheet may result in error code 4004.
Security Scheme Type | OAuth2 |
---|---|
authorizationCode OAuth Flow | Authorization URL: https://app.smartsheet.com/b/authorize Token URL: https://api.smartsheet.com/2.0/token Scopes:
|
A User in Smartsheet must have a primary email address associated with their user account (User.email) and may optionally have one or more alternate email addresses associated with their account (User.alternateEmails). The following operations must be performed using an user's primary email address:
Attempting to specify a user's alternate email address for any of the above operations results in an error.
id | number AlternateEmail Id. |
confirmed | boolean Indicates whether the alternate email address has been confirmed. |
string User's alternate email address. |
{- "id": 8150532427671428,
- "confirmed": true,
- "email": "johnathan.doe@smartsheet.com"
}
Gets a list of the alternate emails for the specified user.
userId required | number User Id |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "pageNumber": 1,
- "pageSize": 50,
- "totalPages": 25,
- "totalCount": 136,
- "data": [
- {
- "id": 8150532427671428,
- "confirmed": true,
- "email": "johnathan.doe@smartsheet.com"
}
]
}
Adds one or more alternate email addresses for the specified user.
This operation is only available to system administrators.
userId required | number User Id |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
string User's alternate email address. |
[ ]
{- "message": "SUCCESS",
- "resultCode": 0,
- "data": [
- {
- "id": 8150532427671428,
- "confirmed": true,
- "email": "johnathan.doe@smartsheet.com"
}
]
}
Gets the specified alternate email.
userId required | number User Id |
alternateEmailId required | number Alternate Email Id |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternateEmailId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "id": 8150532427671428,
- "confirmed": true,
- "email": "johnathan.doe@smartsheet.com"
}
Deletes the specified alternate email address for the specified user.
userId required | number User Id |
alternateEmailId required | number Alternate Email Id |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternatEmailId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -X DELETE
{- "message": "SUCCESS",
- "resultCode": 0
}
Makes the specified alternate email address to become the primary email address for the specified user.
The alternate email address can only be made primary if both conditions are met:
userId required | number User Id |
alternateEmailId required | number Alternate Email Id |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternatEmailId}/makeprimary \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -H "Content-Type: application/json" \ -X POST
{- "message": "SUCCESS",
- "resultCode": 0,
- "data": [
- {
- "id": 8150532427671428,
- "confirmed": true,
- "email": "johnathan.doe@smartsheet.com"
}
]
}
Like the Smartsheet app, the Smartsheet API allows uploading files to sheets, rows, and comments. You can upload a file by performing either a simple upload or a multipart upload.
A simple upload allows you to add a single file attachment to the specified object. For example, you can perform a simple upload to attach a file to a sheet, attach a file to a row, or attach a file to a comment.
A multipart upload allows you to add a single file attachment to the specified object (that is, attach a file to a sheet, row, or comment), or to create an object and attach a file using a single request. For example, you can perform a multipart upload to add a new comment that contains a single file attachment or to add a new discussion to a sheet that contains a single file attachment.
The max file size for uploads through the API is limited to 30mb.
NOTE: Posting an attachment is a resource-intensive operation and incurs 10 additional requests against the rate limit.
A multipart upload request must include the following HTTP headers:
Header | Description |
---|---|
Content-Length | The length of the request payload. |
Content-Type | Must be set to multipart/form-data, and include the boundary string that separates the parts in the request payload. |
The request body of a multipart upload request contains one or more parts, each part containing either JSON or a file to upload. The request body must contain at least one part. Each part must start with the boundary string specified in the Content-Type request header, and must contain the following part headers:
Header | Description |
---|---|
Content-Disposition | Contains the following semicolon-delimited items:
|
Content-Type | The content type of the part: application/json for JSON objects, or the applicable MIME type for file parts |
The last part in the request must be followed by the boundary string, followed by two hyphens.
The documentation for each operation that supports multipart uploads specifies the number and names of parts that are expected for the operation. File parts must have the part name "file", and documentation for operations which allow for JSON object parts specify the required part name for the JSON part.
The following example shows a multipart upload request that creates a comment containing the specified text and file attachment:
POST https://api.smartsheet.com/2.0/sheets/4509093797881732/discussions/2889925487028100/comments
Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Length: 29008
Content-Type: multipart/form-data; boundary=----gU8h01zAAp3LagBr
------gU8h01zAAp3LagBr
Content-Disposition: form-data; name="comment"
Content-Type: application/json
{ "text": "Please review the attached image." }
------gU8h01zAAp3LagBr
Content-Disposition: form-data; name="file"; filename="picture.jpg"
Content-Type: image/jpeg
*< Binary content for file >*
------gU8h01zAAp3LagBr--
NOTE: Most programming languages have libraries that can be used to assemble multipart requests.
To perform this kind of upload, you must set specific headers to tell Smartsheet about the file. The following three headers are required:
Header | Description |
---|---|
Content-Disposition | attachment to tell the API that a file is in the body of the POST request, followed by a semicolon, followed by filename= and the URL-encoded filename in quotes |
Content-Length | Must be set to the size of the file, in bytes. For example to determine file size using in UNIX:
|
Content-Type | Can be left blank if it is not known (but must be present); Smartsheet makes its best guess based on the extension of the file. |
The following example request shows a simple upload that adds a file attachment to a sheet:
POST https://api.smartsheet.com/2.0/sheets/4509093797881732/attachments
Authorization: Bearer ll352u9jujauoqz4gstvsae05
Content-Disposition: attachment; filename="ProgressReport.docx"
Content-Type: application/msword
Content-Length: 5463
*< Binary content for file >*
As shown in this example, the contents of the file is included in the body of the POST
request. In most programming languages, this is done by reading the file from an input stream and writing it out to the output stream of the HTTP request.
id | number Attachment Id. |
parentId | number The Id of the parent. |
attachmentType | string Attachment type. * types are not supported for Smartsheet.gov accounts. |
attachmentSubType | string Attachment sub type. * type is for EGNYTE values and the rest are GOOGLE_DRIVE values. |
mimeType | string Attachment MIME type. |
parentType | string The type of object the attachment belongs to. |
string or number | |
object
| |
name | string Attachment name. |
sizeInKb | number The size of the file, if the attachmentType is FILE. |
url | string Attachment temporary URL (files only). |
urlExpiresInMillis | number Attachment temporary URL time to live (files only). |
{- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
attachmentSubType | string Attachment sub type. * type is for EGNYTE values and the rest are GOOGLE_DRIVE values. |
attachmentType | string Attachment type. * types are not supported for Smartsheet.gov accounts. |
description | string |
name | string |
url | string |
{- "attachmentSubType": "DOCUMENT",
- "attachmentType": "BOX_COM",
- "description": "string",
- "name": "string",
- "url": "string"
}
Gets a list of all attachments that are on the sheet, including sheet, row, and discussion-level attachments.
sheetId required | number Sheet Id of the sheet being accessed. |
page | number Default: 1 Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
pageSize | number Default: 100 The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If neither pageSize nor page is specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100. |
includeAll | boolean Default: false If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified). |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "pageNumber": 1,
- "pageSize": 50,
- "totalPages": 25,
- "totalCount": 136,
- "data": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
]
}
Attaches a file to the sheet. The URL can be any of the following:
For multipart uploads please use "multipart/form-data" content type.
sheetId required | number Sheet Id of the sheet being accessed. |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
{- "version": 0,
- "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
}
Fetches a temporary URL that allows you to download an attachment. The urlExpiresInMillis attribute tells you how long the URL is valid.
sheetId required | number Sheet Id of the sheet being accessed. |
attachmentId required | string ID of the attachment |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
Deletes the attachment specified in the URL.
sheetId required | number Sheet Id of the sheet being accessed. |
attachmentId required | string ID of the attachment |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -X DELETE
{- "message": "SUCCESS",
- "resultCode": 0
}
Gets a list of all versions of the given attachmentId in order from newest to oldest.
sheetId required | number Sheet Id of the sheet being accessed. |
attachmentId required | string ID of the attachment |
page | number Default: 1 Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
pageSize | number Default: 100 The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If neither pageSize nor page is specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100. |
includeAll | boolean Default: false If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified). |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "pageNumber": 1,
- "pageSize": 50,
- "totalPages": 25,
- "totalCount": 136,
- "data": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
]
}
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.
sheetId required | number Sheet Id of the sheet being accessed. |
attachmentId required | string ID of the attachment |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -H "Content-Type: application/msword" \ -H 'Content-Disposition: attachment; filename="ProgressReport.docx"' \ -H "Content-Length: FILE_SIZE" \ -X POST \ --data-binary @ProgressReport.docx
{- "version": 0,
- "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
}
Deletes all versions of the attachment corresponding to the specified attachmentId. For attachments with multiple versions, this effectively deletes the attachment from the object that it’s attached to.
sheetId required | number Sheet Id of the sheet being accessed. |
attachmentId required | string ID of the attachment |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -X DELETE
{- "message": "SUCCESS",
- "resultCode": 0
}
Attaches a file to the comment. The URL can be any of the following:
This operation can be performed using a simple upload or a multipart upload.
sheetId required | number Sheet Id of the sheet being accessed. |
commentId required | string ID of the comment |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
{- "version": 0,
- "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
}
Gets a list of all attachments that are in the discussion.
sheetId required | number Sheet Id of the sheet being accessed. |
discussionId required | string ID of the discussion |
page | number Default: 1 Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
pageSize | number Default: 100 The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If neither pageSize nor page is specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100. |
includeAll | boolean Default: false If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified). |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/attachments \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "pageNumber": 1,
- "pageSize": 50,
- "totalPages": 25,
- "totalCount": 136,
- "data": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
]
}
Gets a list of all attachments that are on the row, including row and discussion-level attachments.
sheetId required | number Sheet Id of the sheet being accessed. |
rowId required | number Row Id in the sheet being accessed. |
page | number Default: 1 Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
pageSize | number Default: 100 The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If neither pageSize nor page is specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100. |
includeAll | boolean Default: false If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified). |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "pageNumber": 1,
- "pageSize": 50,
- "totalPages": 25,
- "totalCount": 136,
- "data": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
]
}
Attaches a file to the row. The URL can be any of the following:
For multipart uploads please use "multipart/form-data" content type.
sheetId required | number Sheet Id of the sheet being accessed. |
rowId required | number Row Id in the sheet being accessed. |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
{- "version": 0,
- "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
}
Automation is a catch-all term for approvals, notifications, and update requests. You can delete, update, or retrieve various automation settings through the API. You cannot create new automation rules programmatically.
id | number AutomationRule Id. |
object or object or object | |
string or number A timestamp of when the rule was originally added. | |
object
| |
disabledReason | string Machine-readable reason a rule is disabled:
|
disabledReasonText | string Descriptive reason a rule is disabled. |
enabled | boolean If true, indicates that the rule is active. |
string or number The datetime for when the change was made to the rule. | |
object
| |
name | string Rule name as shown in the UI. |
userCanModify | boolean If true, indicates that the current user can modify the rule. |
{- "id": 0,
- "action": {
- "notifyAllSharedUsers": true
}, - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "disabledReason": "APPROVAL_COLUMN_MISSING",
- "disabledReasonText": "string",
- "enabled": true,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "modifiedBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "userCanModify": true
}
notifyAllSharedUsers | boolean If true, notifications are sent to all users shared to the sheet. |
includedColumnIds | Array of numbers Specifies which columns to include in message. |
type | string Enum: "APPROVAL_REQUEST_ACTION" "NOTIFICATION_ACTION" "UPDATE_REQUEST_ACTION" |
frequency | string Enum: "DAILY" "HOURLY" "IMMEDIATELY" "WEEKLY" |
includeAllColumns | boolean Default: true If true, all columns are included in email contents. |
includeAttachments | string If true, all attachments are included in email contents. |
includeDiscussions | boolean If true, all discussions are included in email contents. |
message | string Email body. |
subject | string Email subject line. |
{- "recipientColumnIds": [
- 0
], - "includedColumnIds": [
- 0
], - "type": "APPROVAL_REQUEST_ACTION",
- "frequency": "DAILY",
- "includeAllColumns": true,
- "includeAttachments": "string",
- "includeDiscussions": true,
- "message": "string",
- "subject": "string"
}
Returns all automation rules associated with the specified sheet.
Multistep workflows are not returned via the API. Instead, you'll see an error 400 - 1266: This rule is not accessible through the API. Only single-action notifications, approval requests, or update requests qualify.
For users of Smartsheet for Slack, note that Slack notifications are not returned.
sheetId required | number Sheet Id of the sheet being accessed. |
includeAll | boolean Default: false If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified). |
page | number Default: 1 Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
pageSize | number Default: 100 The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If neither pageSize nor page is specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100. |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "pageNumber": 1,
- "pageSize": 50,
- "totalPages": 25,
- "totalCount": 136,
- "data": [
- {
- "id": 0,
- "action": {
- "notifyAllSharedUsers": true
}, - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "disabledReason": "APPROVAL_COLUMN_MISSING",
- "disabledReasonText": "string",
- "enabled": true,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "modifiedBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "userCanModify": true
}
]
}
Returns the specified automation rule, including any action values.
sheetId required | number Sheet Id of the sheet being accessed. |
automationRuleId required | string The Id of an Automation Rule |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "id": 0,
- "action": {
- "notifyAllSharedUsers": true
}, - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "disabledReason": "APPROVAL_COLUMN_MISSING",
- "disabledReasonText": "string",
- "enabled": true,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "modifiedBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "userCanModify": true
}
Updates an existing automation rule.
When sending an AutomationRule, you must always specify action.type and it must match the existing rule type.
sheetId required | number Sheet Id of the sheet being accessed. |
automationRuleId required | string The Id of an Automation Rule |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
{- "id": 0,
- "action": {
- "notifyAllSharedUsers": true
}, - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com"
}, - "disabledReason": "APPROVAL_COLUMN_MISSING",
- "disabledReasonText": "string",
- "enabled": true,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "modifiedBy": {
- "email": "jane.doe@smartsheet.com"
}, - "name": "string",
- "userCanModify": true
}
{- "version": 0,
- "failedItems": [
- {
- "rowId": 0,
- "error": {
- "refId": "string",
- "errorCode": 0,
- "message": "string"
}, - "index": 0
}
], - "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "id": 0,
- "action": {
- "notifyAllSharedUsers": true
}, - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "disabledReason": "APPROVAL_COLUMN_MISSING",
- "disabledReasonText": "string",
- "enabled": true,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "modifiedBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "userCanModify": true
}
}
Deletes an automation rule.
sheetId required | number Sheet Id of the sheet being accessed. |
automationRuleId required | string The Id of an Automation Rule |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -X DELETE
{- "version": 0,
- "failedItems": [
- {
- "rowId": 0,
- "error": {
- "refId": "string",
- "errorCode": 0,
- "message": "string"
}, - "index": 0
}
], - "message": "SUCCESS",
- "resultCode": 0
}
Reason | Description |
---|---|
APPROVAL_COLUMN_MISSING | This rule's approval status column has been deleted. |
APPROVAL_COLUMN_WRONG_TYPE | The approval column must be a dropdown column. |
AUTOMATION_NOT_ENABLED_FOR_ORG | To create or edit automated actions, you need to upgrade your organization account to a Business or Enterprise plan. |
COLUMN_MISSING | A column referenced by this rule has been deleted. |
COLUMN_TYPE_INCOMPATIBLE | A column referenced by this rule has been changed to an incompatible column type. |
NO_POTENTIAL_RECIPIENTS | This rule has no recipients that will be able to receive notifications based on this sheet's permission settings or this account's approved domain sharing list. |
NO_VALID_SELECTED_COLUMNS | All selected columns for this rule have been deleted. |
columnId | number The Id of the column that the cell is located in. |
columnType | string Only returned if the include query string parameter contains columnType. |
conditionalFormat | string The format descriptor describing this cell's conditional format. Only returned if the include query string parameter contains format and this cell has a conditional format applied. |
displayValue | string Visual representation of cell contents, as presented to the user in the UI. |
format | string The format descriptor. Only returned if the include query string parameter contains format and this cell has a non-default format applied. |
formula | string The formula for a cell, if set, for instance =COUNTM([Assigned To]3). Note that calculation errors or problems with a formula do not cause the API call to return an error code. Instead, the response contains the same value as in the UI, such as cell.value = "#CIRCULAR REFERENCE". |
object | |
object | |
object | |
Array of objects | |
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. | |
overrideValidation | boolean (Admin only) Indicates whether the cell value can contain a value outside of the validation limits (value = true). When using this parameter, you must also set strict to false to bypass value type checking. This property is honored for POST or PUT actions that update rows. |
strict | boolean Set to false to enable lenient parsing. Defaults to true. You can specify this attribute in a request, but it is never present in a response. |
string or number or boolean A string, number, or a Boolean value -- depending on the cell type and the data in the cell. Cell values larger than 4000 characters are silently truncated. An empty cell returns no value. |
{- "columnId": 0,
- "columnType": "string",
- "conditionalFormat": "string",
- "displayValue": "string",
- "format": "string",
- "formula": "string",
- "hyperlink": {
- "reportId": 0,
- "sheetId": 0,
- "sightId": 0,
- "url": "string"
}, - "image": {
- "altText": "string",
- "height": 0,
- "id": "string",
- "width": 0
}, - "linkInFromCell": {
- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}, - "linksOutToCells": [
- {
- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}
], - "objectValue": {
- "objectType": "ABSTRACT_DATETIME"
}, - "overrideValidation": true,
- "strict": true,
- "value": "string"
}
string or number | |
object User object containing the name and email of the user that made the change. | |
columnId | number The Id of the column that the cell is located in. |
columnType | string Only returned if the include query string parameter contains columnType. |
conditionalFormat | string The format descriptor describing this cell's conditional format. Only returned if the include query string parameter contains format and this cell has a conditional format applied. |
displayValue | string Visual representation of cell contents, as presented to the user in the UI. |
format | string The format descriptor. Only returned if the include query string parameter contains format and this cell has a non-default format applied. |
formula | string The formula for a cell, if set, for instance =COUNTM([Assigned To]3). Note that calculation errors or problems with a formula do not cause the API call to return an error code. Instead, the response contains the same value as in the UI, such as cell.value = "#CIRCULAR REFERENCE". |
object | |
object | |
object | |
Array of objects | |
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. | |
overrideValidation | boolean (Admin only) Indicates whether the cell value can contain a value outside of the validation limits (value = true). When using this parameter, you must also set strict to false to bypass value type checking. This property is honored for POST or PUT actions that update rows. |
strict | boolean Set to false to enable lenient parsing. Defaults to true. You can specify this attribute in a request, but it is never present in a response. |
string or number or boolean A string, number, or a Boolean value -- depending on the cell type and the data in the cell. Cell values larger than 4000 characters are silently truncated. An empty cell returns no value. |
{- "modifiedAt": "2019-08-24T14:15:22Z",
- "modifiedBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "columnId": 0,
- "columnType": "string",
- "conditionalFormat": "string",
- "displayValue": "string",
- "format": "string",
- "formula": "string",
- "hyperlink": {
- "reportId": 0,
- "sheetId": 0,
- "sightId": 0,
- "url": "string"
}, - "image": {
- "altText": "string",
- "height": 0,
- "id": "string",
- "width": 0
}, - "linkInFromCell": {
- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}, - "linksOutToCells": [
- {
- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}
], - "objectValue": {
- "objectType": "ABSTRACT_DATETIME"
}, - "overrideValidation": true,
- "strict": true,
- "value": "string"
}
columnId | number Column Id of the linked cell. |
rowId | number Row Id of the linked cell. |
sheetId | number Sheet Id of the sheet that the linked cell belongs to. |
sheetName | string Sheet name of the linked cell. |
status | string
|
{- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}
days | number The number of days for this duration. |
elapsed | boolean If true, indicates this duration represents elapsed time, which ignores non-working time. |
hours | number The number of hours for this duration. |
milliseconds | number The number of milliseconds for this duration. |
minutes | number The number of minutes for this duration. |
negative | boolean When used as a predecessor's lag value, indicates whether the lag is negative (if true), or positive (false). The individual duration values themselves (for example, days, hours, or minutes) is always positive. |
objectType | string Value: "DURATION" |
seconds | number The number of seconds for this duration. |
weeks | number The number of weeks for this duration. |
{- "days": 0,
- "elapsed": true,
- "hours": 0,
- "milliseconds": 0,
- "minutes": 0,
- "negative": true,
- "objectType": "DURATION",
- "seconds": 0,
- "weeks": 0
}
reportId | number If non-null, this hyperlink is a link to the report with this Id. |
sheetId | number If non-null, this hyperlink is a link to the sheet with this Id. |
sightId | number If non-null, this hyperlink is a link to the dashboard with this Id. |
url | string When the hyperlink is a URL link, this property contains the URL value. When the hyperlink is a dashboard/report/sheet link (that is, dashboardId, reportId, or sheetId is non-null), this property contains the permalink to the dashboard, report, or sheet. |
{- "reportId": 0,
- "sheetId": 0,
- "sightId": 0,
- "url": "string"
}
objectType | string Enum: "ABSTRACT_DATETIME" "CONTACT" "DATE" "DATETIME" "DURATION" "MULTI_CONTACT" "MULTI_PICKLIST" "PREDECESSOR_LIST" |
{- "objectType": "ABSTRACT_DATETIME"
}
rowId | number The Id of the predecessor row. |
type | string Type of the predecessor:
|
inCriticalPath | boolean True if this predecessor is in the critical path. |
invalid | boolean True if the row referenced by rowId is not a valid row in this sheet, or there is a circular reference (displayed in the Smartsheet app as "#REF") Omitted if false. |
object In a project sheet, represents a value in a duration cell, or a lag value of a predecessor. | |
rowNumber | number The row number of the predecessor row. Omitted if invalid is true. |
{- "rowId": 0,
- "type": "FF",
- "inCriticalPath": true,
- "invalid": true,
- "lag": {
- "days": 0,
- "elapsed": true,
- "hours": 0,
- "milliseconds": 0,
- "minutes": 0,
- "negative": true,
- "objectType": "DURATION",
- "seconds": 0,
- "weeks": 0
}, - "rowNumber": 0
}
objectType | string Value: "PREDECESSOR_LIST" |
Array of objects |
{- "objectType": "ABSTRACT_DATETIME",
- "predecessors": [
- {
- "rowId": 0,
- "type": "FF",
- "inCriticalPath": true,
- "invalid": true,
- "lag": {
- "days": 0,
- "elapsed": true,
- "hours": 0,
- "milliseconds": 0,
- "minutes": 0,
- "negative": true,
- "objectType": "DURATION",
- "seconds": 0,
- "weeks": 0
}, - "rowNumber": 0
}
]
}
Gets the cell modification history.
sheetId required | number Sheet Id of the sheet being accessed. |
rowId required | number Row Id in the sheet being accessed. |
columnId required | number Column Id in the sheet being accessed. |
include | string A comma-separated list of elements to copy:
|
pageSize | number Default: 100 The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If neither pageSize nor page is specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100. |
page | number Default: 1 Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
level | integer Default: 1 Specifies whether new functionality, such as multi-contact data is returned in a backwards-compatible, text format (level=0, default), multi-contact data (level=1), or multi-picklist data (level=2). |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history?include=columnType' \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "pageNumber": 1,
- "pageSize": 50,
- "totalPages": 25,
- "totalCount": 136,
- "data": [
- {
- "modifiedAt": "2019-08-24T14:15:22Z",
- "modifiedBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "columnId": 0,
- "columnType": "string",
- "conditionalFormat": "string",
- "displayValue": "string",
- "format": "string",
- "formula": "string",
- "hyperlink": {
- "reportId": 0,
- "sheetId": 0,
- "sightId": 0,
- "url": "string"
}, - "image": {
- "altText": "string",
- "height": 0,
- "id": "string",
- "width": 0
}, - "linkInFromCell": {
- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}, - "linksOutToCells": [
- {
- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}
], - "objectValue": {
- "objectType": "ABSTRACT_DATETIME"
}, - "overrideValidation": true,
- "strict": true,
- "value": "string"
}
]
}
Creating or updating cell links via the cell.linkInFromCell attribute is a special operation. A given row or cell update operation may contain only link updates, or no link updates. Attempting to mix row/cell updates with cell link updates results in error code 1115. Additionally, a CellLink object can only be added to an existing cell, so the cell.linkInFromCell attribute is not allowed when POSTing a new row to a sheet.
When creating a cell link, cell.value must be null (the data is pulled from the linked cell).
A cell may not contain both a hyperlink and a cell link, so hyperlink and linkInFromCell may never both be non-null at the same time.
Cell objects retrieved through the Smartsheet APIs have two main attributes representing cell values: Cell.value, and Cell.displayValue. A third attribute, Cell.objectValue is currently used only for adding and updating predecessors, or for multi-contact or multi-picklist details, such as email addresses or values in a multi-picklist. An empty cell returns no value.
Cell.displayValue is always a string and is only returned for certain column types (see below). It represents the formatted value as it should be displayed to an end-user. For example, if a TEXT_NUMBER column is formatted as a US Dollar currency, its value may be a number like 1234.5678, but its displayValue is "$1,234.57".
Cell.value represents a cell's raw value and can be one of the following primitive JSON types: string, number, or Boolean, depending on the column type. An empty cell returns no value. Complex types are represented as strings, formatted as described below:
Column Type | Possible Types for Cell.value | Returns Cell.displayValue? |
---|---|---|
ABSTRACT_DATETIME | string: a project date and time in ISO-8601 format, or a free-form text value. number: see Dates and Times for how to request dates to be returned as numbers. |
No. |
CHECKBOX | Boolean: true if the checkbox is checked, false if unchecked, no value if the cell hasn't been touched yet. string: a free-form text value. |
No. |
CONTACT_LIST | string: an email address representing a contact, or a free-form text value. | Yes: same as value for free-form strings; for contacts, the contact's name if any, else their email address. |
DATE | string: a date in ISO-8601 format, or a free-form text value. number: see Dates and Times for how to request dates to be returned as numbers. |
No. |
DURATION | string: a duration value such as "4d 6h 30m" in the user's locale, or a free-form text value. See the [Help Center](<%= PROJECT_COLUMN_HELP_URL %>) for more information on durations. |
Yes: same as value |
MULTI_CONTACT_LIST | string: only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying, otherwise the column type is TEXT_NUMBER. | Yes: same as value; to see actual email addresses, see below. |
MULTI_PICKLIST | string: only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying, otherwise the column type is TEXT_NUMBER. | Yes: same as value; to see objectValue, see below. |
PICKLIST | string: one of the picklist's column options, or a free-form text value. number: numeric values |
Yes: same as value for strings; for number values, the number with formatting applied. |
PREDECESSOR | string: a comma-delimited predecessor list such as "12FS +3d 4h, 14SS", or a free-form text value. See the [Help Center](<%= PROJECT_COLUMN_HELP_URL %>) for more information on predecessors. |
Yes: same as value |
TEXT_NUMBER | string: free-form text values number: numeric values |
Yes: same as value for strings; for number values, the number with formatting applied. |
Cell.objectValue is an object representation of a cell's value and is currently used for adding or updating predecessor cell values, or for multi-contact details, such as email addresses.
The flexibility in cell value data types is a powerful feature in the Smartsheet application; however, it poses a challenge for an API in terms of parsing. Being too flexible might result in unexpected behavior. For instance, if you write code to post a Date value to a Smartsheet and the API operation succeeds, you might assume that the date value you sent was interpreted as date. What happens if you posted your date in the wrong format? Do you really want Smartsheet to keep the malformed date as a string value? Probably not.
To address this problem, the Smartsheet API employs a simple scheme to indicate whether you want a more predictable and strict interface or a more flexible one. By default, a cell value is expected to conform to "strict" rules for the type of the cell's column. If an input value doesn't conform, the API returns error code 1042.
If, however, you want the same flexibility as the Smartsheet Web app, you can disable the strict rules, and we’ll do our best to make sense of it. To enable lenient parsing simply include "strict": false in the Cell object in your request body.
NOTE: How does strict cell value parsing compare to cell validation settings? Strict cell value parsing determines how string values are parsed. It is set on a per-call basis. In contrast, cell validation is part of the column definition. The overrideValidation property is restricted to sheet admins and does not override strict parsing.
The parsing rules for the various column types are as follows:
ABSTRACT_DATETIME
Value | Description |
---|---|
lenient | Smartsheet attempts to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, Smartsheet recognizes the date and stores it as such. All other values are simply text values. |
strict | The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of numericDates set to true to have Smartsheet convert epoch time to human readable dates. See Dates and Times for more information. |
CHECKBOX
Value | Description |
---|---|
lenient | Boolean values and string values of true and false are handled the same as strict. All other values are saved as text values. |
strict | Only Boolean values (true or false) are valid. |
CONTACT_LIST
Value | Description |
---|---|
lenient | If the value is a valid email address, Smartsheet handles it the same as strict. If not, Smartsheet saves the value as a text value. |
strict | The value must be a valid email address. If displayValue is set, Smartsheet uses that as the name; otherwise, if Smartsheet finds a match among the the access token owner's contacts, Smartsheet associates this cell with that existing contact. |
NOTE: See Contact List Columns for more information.
DATE
Value | Description |
---|---|
lenient | Smartsheet attempts to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, Smartsheet recognizes the date and stores it as such. All other values are simply text values. |
strict | The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of numericDates set to true to have Smartsheet convert epoch time to human readable dates. See Dates and Times for more information. |
DURATION
Value | Description |
---|---|
lenient | Numeric values are treated as duration values in days. String values which are valid duration strings in the user's locale are treated as durations, and any other values are treated as free-form text values. |
strict | Only valid duration strings in the user's locale are valid. Information on duration strings can be found in [Help Center](<%= PROJECT_COLUMN_HELP_URL %>). |
NOTE: You may use the query string parameter projectParseLocale with a supported locale string to force parsing in the specified locale (for example, using en_US lets you send in English values regardless of the user's locale).
MULTI_CONTACT_LIST
Value | Description |
---|---|
N/A | Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference. |
MULTI_PICKLIST
Value | Description |
---|---|
N/A | Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference. |
PICKLIST
Value | Description |
---|---|
lenient | All numeric and text values are valid. Formatted numbers are parsed like TEXT_NUMBER formatted numbers. |
strict | The value must be a string and must be one of the options for the picklist. |
PREDECESSOR
Value | Description |
---|---|
N/A | Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference. |
TEXT_NUMBER
Value | Description |
---|---|
lenient | All numeric and text values are valid. Formatted numbers passed as text values, such as currencies ("$5,000"), percentages ("50%"), or decimals ("100.5") are parsed to their numeric equivalents, based on the locale of the access token owner, with the proper formatting enabled for the cell. |
strict | All numeric and text values are valid and are interpreted literally. |
NOTE: The Smartsheet application only supports numeric values in the range -9007199254740992 to 9007199254740992. If using strict parsing, any numeric value outside that range results in error code 1148. If using lenient parsing, the value is silently converted to text.
With columns of type CONTACT_LIST, the cell attributes value and displayValue are treated independently. The contact’s email address is represented by value, while the contact’s name (and the value displayed in the cell in the Smartsheet app) is represented by displayValue.
When creating or updating cells for a contact list column, the displayValue attribute works as follows:
You can create and modify hyperlinks by using any API operation that creates or updates cell data. When creating or updating a hyperlink, cell.value may be set to a string value or null. If null, the cell's value is derived from the hyperlink:
For details about working with images in cells, see Cell Images.
altText | string Alternate text for the image. |
height | number Original height (in pixels) of the uploaded image. |
id | string Image Id. |
width | number Original width (in pixels) of the uploaded image. |
{- "altText": "string",
- "height": 0,
- "id": "string",
- "width": 0
}
imageId | string Image Id. |
object The error caused by the failed item. | |
height | number Image height in pixels. |
url | string Temporary URL that can be used to retrieve the image. This attribute can be present in a response but is never specified in a request. |
width | number Image width in pixels. |
{- "imageId": "string",
- "error": {
- "refId": "string",
- "errorCode": 0,
- "message": "string"
}, - "height": 0,
- "url": "string",
- "width": 0
}
Array of objects | |
urlExpiresInMillis | number Milliseconds before the URLs within imageUrls expire. |
{- "imageUrls": [
- {
- "imageId": "string",
- "error": {
- "refId": "string",
- "errorCode": 0,
- "message": "string"
}, - "height": 0,
- "url": "string",
- "width": 0
}
], - "urlExpiresInMillis": 0
}
Gets a list of URLs that can be used to retrieve the specified cell images.
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
imageId | string Image Id. |
object The error caused by the failed item. | |
height | number Image height in pixels. |
url | string Temporary URL that can be used to retrieve the image. This attribute can be present in a response but is never specified in a request. |
width | number Image width in pixels. |
{- "imageId": "string",
- "error": {
- "refId": "string",
- "errorCode": 0,
- "message": "string"
}, - "height": 0,
- "url": "string",
- "width": 0
}
{- "imageUrls": [
- {
- "imageId": "string",
- "error": {
- "refId": "string",
- "errorCode": 0,
- "message": "string"
}, - "height": 0,
- "url": "string",
- "width": 0
}
], - "urlExpiresInMillis": 0
}
Uploads an image to the specified cell within a sheet.
sheetId required | number Sheet Id of the sheet being accessed. |
rowId required | number Row Id in the sheet being accessed. |
columnId required | number Column Id in the sheet being accessed. |
altText | string Url-encoded alternate text for the image |
overrideValidation | boolean Default: false You may use the query string parameter overrideValidation with a value of true to allow a cell value outside of the validation limits. You must specify strict with a value of false to bypass value type checking. |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
Content-Disposition | string Should be equal to "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 Example: attachment; filename="ProgressReport.docx" |
Content-Length | integer 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 Example: 5463 |
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages?altText=my%20image' \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -H "Content-Type: image/jpeg" \ -H 'Content-Disposition: attachment; filename="picture.jpg"' \ -H "Content-Length: FILE_SIZE" \ -X POST \ --data-binary @picture.jpg
{- "version": 0,
- "failedItems": [
- {
- "rowId": 0,
- "error": {
- "refId": "string",
- "errorCode": 0,
- "message": "string"
}, - "index": 0
}
], - "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "id": 0,
- "sheetId": 0,
- "accessLevel": "ADMIN",
- "attachments": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
], - "cells": [
- {
- "columnId": 0,
- "columnType": "string",
- "conditionalFormat": "string",
- "displayValue": "string",
- "format": "string",
- "formula": "string",
- "hyperlink": {
- "reportId": 0,
- "sheetId": 0,
- "sightId": 0,
- "url": "string"
}, - "image": {
- "altText": "string",
- "height": 0,
- "id": "string",
- "width": 0
}, - "linkInFromCell": {
- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}, - "linksOutToCells": [
- {
- "columnId": 0,
- "rowId": 0,
- "sheetId": 0,
- "sheetName": "string",
- "status": "BLOCKED"
}
], - "objectValue": {
- "objectType": "ABSTRACT_DATETIME"
}, - "overrideValidation": true,
- "strict": true,
- "value": "string"
}
], - "columns": [
- {
- "autoNumberFormat": {
- "fill": "string",
- "prefix": "string",
- "startingNumber": 0,
- "suffix": "string"
}, - "contactOptions": [
- {
- "email": "string",
- "name": "string"
}
], - "description": "string",
- "format": "string",
- "hidden": true,
- "id": 0,
- "index": 0,
- "locked": true,
- "lockedForUser": true,
- "options": [
- "string"
], - "primary": true,
- "symbol": "string",
- "systemColumnType": "AUTO_NUMBER",
- "tags": [
- "CALENDAR_END_DATE"
], - "title": "string",
- "type": "ABSTRACT_DATETIME",
- "validation": true,
- "version": 0,
- "width": 0
}
], - "conditionalFormat": ",,1,1,,,,,,,,,,,,,",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "discussions": [
- {
- "accessLevel": "ADMIN",
- "id": 0,
- "comments": [
- {
- "attachments": [
- {
- "id": null,
- "parentId": null,
- "attachmentType": null,
- "attachmentSubType": null,
- "mimeType": null,
- "parentType": null,
- "createdAt": null,
- "createdBy": null,
- "name": null,
- "sizeInKb": null,
- "url": null,
- "urlExpiresInMillis": null
}
], - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "discussionId": 0,
- "id": 0,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "text": "string"
}
], - "commentAttachments": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
], - "commentCount": 0,
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "lastCommentedAt": "2019-08-24T14:15:22Z",
- "lastCommentedUser": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "parentId": 0,
- "parentType": "ROW",
- "readOnly": true,
- "title": "string"
}
], - "proofs": {
- "id": 0,
- "originalId": 0,
- "name": "string",
- "proofType": "DOCUMENT",
- "proofRequestUrl": "string",
- "version": 0,
- "lastUpdatedAt": "2019-08-24T14:15:22Z",
- "lastUpdatedBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "isCompleted": true,
- "attachments": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
], - "discussions": [
- {
- "accessLevel": "ADMIN",
- "id": 0,
- "comments": [
- {
- "attachments": [
- null
], - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": null,
- "name": null
}, - "discussionId": 0,
- "id": 0,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "text": "string"
}
], - "commentAttachments": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": null,
- "name": null
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
], - "commentCount": 0,
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "lastCommentedAt": "2019-08-24T14:15:22Z",
- "lastCommentedUser": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "parentId": 0,
- "parentType": "ROW",
- "readOnly": true,
- "title": "string"
}
]
}, - "expanded": true,
- "filteredOut": true,
- "format": ",,1,1,,,,,,,,,,,,,",
- "inCriticalPath": true,
- "locked": true,
- "lockedForUser": true,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "modifiedBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "permaLink": "string",
- "rowNumber": 1,
- "version": 0
}
}
object Object that describes how the the System Column type of "AUTO_NUMBER" is auto-generated. | |
Array of objects Array of ContactOption objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST. | |
description | string Column description. |
format | string The format descriptor (see Formatting). Only returned if the include query string parameter contains format and this column has a non-default format applied to it. |
hidden | boolean Indicates whether the column is hidden. |
id | number Column Id. |
index | number Column index or position. This number is zero-based. |
locked | boolean Indicates whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin. |
lockedForUser | boolean Indicates whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request. |
options | Array of strings Array of the options available for the column. |
primary | boolean Returned only if the column is the Primary Column (value = true). |
symbol | string When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns. |
systemColumnType | string See System Columns. |
tags | Array of strings Set of tags to indicate special columns. Each element in the array is set to one of the listed enum values. |
title | string Column title. |
type | string See Column Types |
validation | boolean Indicates whether validation has been enabled for the column (value = true). |
version | number
|
width | number Display width of the column in pixels. |
{- "autoNumberFormat": {
- "fill": "string",
- "prefix": "string",
- "startingNumber": 0,
- "suffix": "string"
}, - "contactOptions": [
- {
- "email": "string",
- "name": "string"
}
], - "description": "string",
- "format": "string",
- "hidden": true,
- "id": 0,
- "index": 0,
- "locked": true,
- "lockedForUser": true,
- "options": [
- "string"
], - "primary": true,
- "symbol": "string",
- "systemColumnType": "AUTO_NUMBER",
- "tags": [
- "CALENDAR_END_DATE"
], - "title": "string",
- "type": "ABSTRACT_DATETIME",
- "validation": true,
- "version": 0,
- "width": 0
}
string A parsable email address. | |
name | string Can be a user's name, display name, or free text. |
{- "email": "string",
- "name": "string"
}
Gets a list of all columns belonging to the sheet specified in the URL.
sheetId required | number Sheet Id of the sheet being accessed. |
level | integer Default: 1 specifies whether multi-contact data is returned in a backwards-compatible, text format (level=0, default) or as multi-contact data (level=1). |
page | number Default: 1 Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned. |
pageSize | number Default: 100 The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If neither pageSize nor page is specified, returns all rows in the sheet. If only page is specified, defaults to a page size of 100. |
includeAll | boolean Default: false If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified). |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "pageNumber": 1,
- "pageSize": 50,
- "totalPages": 25,
- "totalCount": 136,
- "data": [
- {
- "id": 0,
- "index": 0,
- "symbol": "string",
- "title": "string",
- "type": "ABSTRACT_DATETIME",
- "validation": true
}
]
}
Inserts one or more columns into the sheet specified in the URL.This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment.
sheetId required | number Sheet Id of the sheet being accessed. |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
A Column object that contains the following attributes
title | string Column title. |
type | string Enum: "ABSTRACT_DATETIME" "CHECKBOX" "CONTACT_LIST" "DATE" "DATETIME" "DURATION" "MULTI_CONTACT_LIST" "MULTI_PICKLIST" "PICKLIST" "PREDECESSOR" "TEXT_NUMBER" |
formula | string The formula for a column, if set, for instance =data@row. |
hidden | boolean Indicates whether the column is hidden. |
index | number Column index or position. This number is zero-based. |
object Object that describes how the the System Column type of "AUTO_NUMBER" is auto-generated. | |
object | |
description | string Column description. |
format | string The format descriptor (see Formatting). Only returned if the include query string parameter contains format and this column has a non-default format applied to it. |
locked | boolean Indicates whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin. |
lockedForUser | boolean Indicates whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request. |
options | Array of strings |
symbol | string When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns. |
systemColumnType | string See System Columns |
validation | boolean Indicates whether validation has been enabled for the column (value = true) |
version | number Read only. The level of the column type. Each element in the array is set to one of the following values:
|
width | number Display width of the column in pixels. |
{- "title": "string",
- "type": "ABSTRACT_DATETIME",
- "formula": "string",
- "hidden": true,
- "index": 0,
- "autoNumberFormat": {
- "fill": "string",
- "prefix": "string",
- "startingNumber": 0,
- "suffix": "string"
}, - "contactOptions": {
- "email": "string",
- "name": "string"
}, - "description": "string",
- "format": "string",
- "locked": true,
- "lockedForUser": true,
- "options": [
- "string"
], - "symbol": "string",
- "systemColumnType": "AUTO_NUMBER",
- "validation": true,
- "version": 0,
- "width": 0
}
{- "message": "SUCCESS",
- "resultCode": 0,
- "result": [
- {
- "id": 0,
- "index": 0,
- "title": "string",
- "type": "ABSTRACT_DATETIME",
- "options": [
- "string"
], - "validation": true,
- "width": 0
}
]
}
Gets the column specified in the URL.
sheetId required | number Sheet Id of the sheet being accessed. |
columnId required | number Column Id in the sheet being accessed. |
level | integer Default: 1 Specifies whether new functionality, such as multi-contact data is returned in a backwards-compatible, text format (level=0, default), multi-contact data (level=1), or multi-picklist data (level=2). |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "id": 0,
- "index": 0,
- "symbol": "string",
- "title": "string",
- "type": "ABSTRACT_DATETIME",
- "validation": true
}
Deletes the column specified in the URL.
sheetId required | number Sheet Id of the sheet being accessed. |
columnId required | number Column Id in the sheet being accessed. |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -X DELETE
{- "message": "SUCCESS",
- "resultCode": 0
}
Updates properties of the column, moves the column, or renames the column.
NOTE:
sheetId required | number Sheet Id of the sheet being accessed. |
columnId required | number Column Id in the sheet being accessed. |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
A Column object that contains the following attributes:
title | string Column title. |
type | string Enum: "ABSTRACT_DATETIME" "CHECKBOX" "CONTACT_LIST" "DATE" "DATETIME" "DURATION" "MULTI_CONTACT_LIST" "MULTI_PICKLIST" "PICKLIST" "PREDECESSOR" "TEXT_NUMBER" |
formula | string The formula for a column, if set, for instance =data@row. |
hidden | boolean Indicates whether the column is hidden. |
index | number Column index or position. This number is zero-based. |
object Object that describes how the the System Column type of "AUTO_NUMBER" is auto-generated. | |
object | |
description | string Column description. |
format | string The format descriptor (see Formatting). Only returned if the include query string parameter contains format and this column has a non-default format applied to it. |
locked | boolean Indicates whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin. |
lockedForUser | boolean Indicates whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request. |
options | Array of strings |
symbol | string When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns. |
systemColumnType | string See System Columns |
validation | boolean Indicates whether validation has been enabled for the column (value = true) |
version | number Read only. The level of the column type. Each element in the array is set to one of the following values:
|
width | number Display width of the column in pixels. |
{- "title": "string",
- "type": "ABSTRACT_DATETIME",
- "formula": "string",
- "hidden": true,
- "index": 0,
- "autoNumberFormat": {
- "fill": "string",
- "prefix": "string",
- "startingNumber": 0,
- "suffix": "string"
}, - "contactOptions": {
- "email": "string",
- "name": "string"
}, - "description": "string",
- "format": "string",
- "locked": true,
- "lockedForUser": true,
- "options": [
- "string"
], - "symbol": "string",
- "systemColumnType": "AUTO_NUMBER",
- "validation": true,
- "version": 0,
- "width": 0
}
{- "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "id": 0,
- "index": 0,
- "options": [
- "string"
], - "title": "string",
- "type": "ABSTRACT_DATETIME",
- "validation": true
}
}
Smartsheet supports the following standard column types, which are represented in a Column object with a type attribute set to one of the following:
Column Type | Column.type Value | Notes |
---|---|---|
Checkbox | CHECKBOX | Checkbox, star, and flag types |
Contact List | CONTACT_LIST | List containing contacts or roles for a project. NOTE: You can use the contactOptions property to specify a pre-defined list of values for the column, which can also become lanes in card view. |
Contact List | MULTI_CONTACT_LIST | List where single cells can contain more than one contact. Only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying. To see email addresses behind the display names, combine an include=objectValue query parameter with a level query parameter. |
Date | DATE | |
Date/Time | ABSTRACT_DATETIME | Represents a project sheet's start and end dates. Only for dependency-enabled project sheets The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) Additionally, the API does not support updating data in the "End Date" column under any circumstance, and does not support updating data in the "Start Date" column if "Predecessor" is set for that row. |
Date/Time | DATETIME | Used only by the following system-generated columns:
|
Dropdown List | PICKLIST | Custom, RYG, Harvey ball, priority types, etc. |
Dropdown List | MULTI_PICKLIST | List where single cells can contain more than one dropdown item. Only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying. To see multi-picklist values behind the display names, combine an include=objectValue query parameter with a level query parameter. |
Duration | DURATION | Only for dependency-enabled project sheets The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) |
Predecessor | PREDECESSOR | Defines what must happen first in a project flow. For more information, see the Predecessor object. Only for dependency-enabled project sheets |
Text/Number | TEXT_NUMBER |
NOTE: See the Cell Reference section for information on getting and setting cell values for the different column types.
In addition to the basic column types above, the Smartsheet app also supports columns that display symbols. These are specialized columns of type CHECKBOX or PICKLIST, whose symbol attribute is set to one of the values below:
Symbols for CHECKBOX columns:
Value | Example |
---|---|
FLAG | ![]() |
STAR | ![]() |
Symbols for PICKLIST columns:
Value | Example |
---|---|
ARROWS_3_WAY | ![]() |
ARROWS_4_WAY | ![]() |
ARROWS_5_WAY | ![]() |
DECISION_SHAPES | ![]() |
DECISION_SYMBOLS | ![]() |
DIRECTIONS_3_WAY | ![]() |
DIRECTIONS_4_WAY | ![]() |
EFFORT | ![]() |
HARVEY_BALLS | ![]() |
HEARTS | ![]() |
MONEY | ![]() |
PAIN | ![]() |
PRIORITY | ![]() |
PRIORITY_HML | ![]() |
PROGRESS | ![]() |
RYG | ![]() |
RYGB | ![]() |
RYGG | ![]() |
SIGNAL | ![]() |
SKI | ![]() |
STAR_RATING | ![]() |
VCR | ![]() |
WEATHER | ![]() |
NOTE: The Smartsheet grid user interface presents several row attributes and features visually as columns, for example, attachments, discussions, row action indicator, or row number. The API does not consider these to be columns, and does not return or otherwise expose them as columns. The only columns returned by the API are user data columns.
In addition to the standard column types and symbols, Smartsheet has a number of system columns, which represent data that is filled in by Smartsheet and whose values cannot be changed by the user. These columns are represented with standard column types, with the Column.systemColumnType attribute set to one of the following:
Column.systemColumnType Value | Column Type | Notes |
---|---|---|
AUTO_NUMBER | TEXT_NUMBER | Columns of this system column type include an AutoNumberFormat object that describes the mask used to generate the value. |
CREATED_BY | CONTACT_LIST | |
CREATED_DATE | DATETIME | |
MODIFIED_BY | CONTACT_LIST | |
MODIFIED_DATE | DATETIME |
A discussion is a container for a number of individual comments in a threaded conversation. For more details, see the Discussion section.
This section describes operations on an individual comment within a discussion thread.
Array of objects Array of attachments on comments. | |
string or number | |
object User object containing name and email of the creator of this comment. | |
discussionId | number Discussion Id of discussion that contains comment. |
id | number Comment Id. |
string or number | |
text | string Comment body. |
{- "attachments": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
], - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "discussionId": 0,
- "id": 0,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "text": "string"
}
Gets the comment specified by commentId.
sheetId required | number Sheet Id of the sheet being accessed. |
commentId required | string ID of the comment |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05"
{- "attachments": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
], - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "discussionId": 0,
- "id": 0,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "text": "string"
}
Updates the text of a comment. NOTE: Only the user that created the comment is permitted to update it.
sheetId required | number Sheet Id of the sheet being accessed. |
commentId required | string ID of the comment |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
text | string Comment body. |
{- "text": "string"
}
{- "version": 0,
- "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "attachments": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
], - "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "discussionId": 0,
- "id": 0,
- "modifiedAt": "2019-08-24T14:15:22Z",
- "text": "string"
}
}
Deletes the comment specified in the URL.
sheetId required | number Sheet Id of the sheet being accessed. |
commentId required | string ID of the comment |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId} \ -H "Authorization: Bearer ll352u9jujauoqz4gstvsae05" \ -X 'DELETE'
{- "version": 0,
- "message": "SUCCESS",
- "resultCode": 0
}
Adds a comment to a discussion. To create a comment with an attachment please use "multipart/form-data" content type.
sheetId required | number Sheet Id of the sheet being accessed. |
discussionId required | string ID of the discussion |
Authorization | string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer ll352u9jujauoqz4gstvsae05 |
Content-Type | string Default: application/json Required for POST and PUT requests. Defines the structure for the request body. |
text | string Comment body. |
{- "text": "string"
}
{- "message": "SUCCESS",
- "resultCode": 0,
- "result": {
- "attachments": [
- {
- "id": 0,
- "parentId": 0,
- "attachmentType": "BOX_COM",
- "attachmentSubType": "DOCUMENT",
- "mimeType": "PNG",
- "parentType": "COMMENT",
- "createdAt": "2019-08-24T14:15:22Z",
- "createdBy": {
- "email": "jane.doe@smartsheet.com",
- "name": "Jane Doe"
}, - "name": "string",
- "sizeInKb": 0,
- "url": "string",
- "urlExpiresInMillis": 0
}
],