openapi: 3.0.3
servers:
- url: https://api.smartsheet.com
info:
title: Smartsheet API Reference
version: 2.0.0
x-logo:
url: /images/smartsheet-horizontal-logo.png
href: https://developers.smartsheet.com
altText: Smartsheet logo
description: >2
Updated 2022-02-16
# Introduction
[Smartsheet](https://www.smartsheet.com/) API 2.0 allows you to programmatically
access and manage your organization's Smartsheet data and account information.
The API allows you to do the following:
* Read and update sheets
* Manage folders and workspaces
* Administer user accounts and organization account
Once you scroll to the Developer Reference section, you can view code examples
in the programming language of your choice by clicking the corresponding tab in
the rightmost pane. Each tab corresponds to a Software Development Kit (SDK) that
Smartsheet provides to make working in that programming language easier. See [SDKs
and Sample Code](#section/API-Basics/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.
# API Basics
## Assume User
Allows an admin to act on behalf of, or impersonate, the user to make API calls.
You might do this to troubleshoot a user problem or cover for vacations and sick
time. As with cURL, the email address used to identify the user must be URI-encoded.
An admin cannot impersonate another admin.
NOTE: You must manually generate a token to assume user.
## Authentication and Access Tokens
The Smartsheet API uses OAuth 2.0 for authentication and authorization. An HTTP
header containing an access token is required to authenticate each request.
* To familiarize yourself with the API, you can generate a raw token. See [Raw
Token Requests](#section/API-Basics/Raw-Token-Requests).
* For additional security and as a recommended best practice, you should build
an integration using OAuth 2.0. During the [OAuth process](#section/Security/Adding-Security-by-Using-OAuth),
you will generate several API keys and, ultimately, each user will generate a
unique access token.
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](#section/Security) for best practices.
## Dates and Times
The Smartsheet API returns all dates and times in the [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time)
time zone in [ISO-8601](https://en.wikipedia.org/wiki/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](tag/users#operation/get-current-user).
You can optionally choose to receive and send dates/times in numeric format, as
milliseconds since the UNIX epoch (midnight on January 1, 1970 in UTC time), using
the query string parameter **numericDates** with a value of **true**. This query
parameter works for any API request.
NOTE: Some SDK methods use language-specific Date objects, which require different
date formats.
## Filtering
You cannot create or update filters using the API; however, you can query which
rows have been filtered out and you can get filter definitions.
For details, see [Filters object](tag/sheetsObjects#section/Filters-Object).
## Formatting
To set or read formatting programmatically, Smartsheet uses a compact format string,
**cell.format**, which looks something like this: `",,1,1,,,,,,,,,,,,,"`. The
position and sample values in this string are explained in the following format
descriptor table:
**Format Descriptor Table**
**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:
* Formats that have not been explicitly set are omitted in the descriptor string.
For example, a cell that has been set to bold and italic, but has no other formats
applied to it, has a format descriptor of ",,1,1,,,,,,,,,,,,,".
* Use GET /serverinfo to return the [FormatTables](tag/commonObjects#section/FormatTables-Object)
object, which tells you both the default settings and what formatting options
are available.
**Applying Formatting**
Use the "include=format" query-string parameter on API operations that return
detailed objects, such as `GET /sheets/{sheetId}` or `GET sheets/{sheetId}/rows/{rowId}`.
If there is formatting other than default settings, the return includes a **format**
property. If an object has conditional formatting, the **format** property returned
will have a **conditionalFormat** value.
Setting the format of a row object or column object through the API simply sets
the baseline format for new or blank cells in that row or column. It does not
affect cells that already have a value.
If you want to change the formatting of cells that already have content, for instance
you want to make a row bold, then you have to set the format for each cell individually.
## Formulas
Formulas are processed per cell in the UI. Use the [Cell object](tag/cellsObjects#section/Cell-Object)
to manipulate formulas via the API.
For requests, use [Update Rows](tag/rows#operation/update-rows) to add or update
the formula in a cell.
For response payloads, formulas (when present) are returned whenever the Cell
object is returned, so for example, GET /sheets/(id) returns the Cell object for
each cell and that object contains a **formula** value when the cell contains
a formula.
## HTTP and REST
The REST URL structure follows typical resource-oriented conventions.
To get a list of sheets, use the following:
`GET https://api.smartsheet.com/2.0/sheets`
This returns a list of Sheet objects, where each sheet has an **id** attribute.
To get details on the sheet with **id 123456**, use the following:
`GET https://api.smartsheet.com/2.0/sheets/123456`
This Id pattern is repeated throughout the API. Columns, rows, cells, comments,
attachments, or any other data element have a unique Id.
If you don't want to make raw HTTP calls, Smartsheet also has several Software
Development Kits (SDKs) that provide a higher level interface for popular programming
languages. For more information, see [SDKs and Sample Code](#section/API-Basics/SDKs-and-Sample-Code).
## HTTP Headers
Unless otherwise specified, all API endpoints expect request body data to be in
[JSON](https://en.wikipedia.org/wiki/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
## HTTP Verbs
Call the API using the following [standard HTTP methods](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html):
* GET (to retrieve an object or list multiple objects in a specific category)
* POST (to create)
* PUT (to modify)
* DELETE
## HTTP Status Codes
Smartsheet uses a combination of [HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
and custom error codes with a descriptive message in JSON-formatted [Error objects](tag/commonObjects#section/Error-Object)
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](https://en.wikipedia.org/wiki/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.
```json
{
"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](#section/Error-Code-List).
## Multi-contact or Multi-picklist: Working with Complex Objects
New column types, such as MULTI_CONTACT_LIST and MULTI_PICKLIST, offer more complex
ways to work with columns. Smartsheet has provided a backwards compatible way
for these payloads to work with your existing integrations while also giving you
a way to query for their content.
With either column type, there are two ways of receiving the response:
* If you do nothing to your code, column types will display as TEXT_NUMBER
* If you use the level query parameter as detailed below, column types will display
as MULTI_CONTACT_LIST or MULTI_PICKLIST and return a complex object (aka a non-primitive
type)
Smartsheet uses two indicators to help you discover changes in the return data
for your API calls:
* level: a query parameter that is incremented when a new feature or column type
is added
* version: each element in the Columns array is set to one of the following values:
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.
## Object Details vs List Summaries
Many of the List All commands, for example, `GET /sheets`, return only an abbreviated
object for each object returned. For full details, read a single item, such as
`GET /sheets/{sheetId}`. In many cases, you can refine the exact object properties
to be returned by using **include** and **exclude** query parameters.
The JSON representation of the objects returned from the List All REST endpoints
will only include a subset of the properties documented here. However, the objects
returned from the Java and C# SDKs will represent the omitted properties with
NULLs.
## Query Strings
Many API calls can be modified by including one or more of these common query
strings:
Query Parameter | Type | Description | More Info |
-----|-----|-----|-----|
**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](#section/Work-at-Scale/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](#section/API-Basics/Formatting)
**includeAll** | Boolean | If **true**, includes all results, for example, **includeAll=true**.
| [Paging](#section/Work-at-Scale/Paging)
**numericDates** | Boolean | If **true**, allows you to input or receive dates
in numeric format, for example, **numericDates=true**. | [Dates and Times](#section/API-Basics/Dates-and-Times)
**page** | String | Specifies which page to return, for example, **page=4**. |
[Paging](#section/Work-at-Scale/Paging)
**pageSize** | Number | Specifies the maximum number of items to return per page,
for example, **pageSize=25**. | [Paging](#section/Work-at-Scale/Paging)
NOTE: Query strings are case sensitive. If you do not see the expected response,
confirm that your query is formatted correctly.
## Raw Token Requests
If you want to get started quickly, or are developing a standalone application
that can run with your credentials, follow these instructions:
1. Click the "Account" button in the upper-right corner of the Smartsheet screen,
and then click "Personal Settings".
2. Click the "API Access" tab.
3. Click the "Generate new access token" button to obtain an access token.
The access token must be sent with every API call in an HTTP authorization header
(except for the requests to Get Access Token or Refresh Access Token). Once you
have an access token, include it in the **Authorization** header for every request
you make:
`Authorization: Bearer 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.
## SDKs and Sample Code
Smartsheet has Software Development Kits (SDKs) providing a higher level interface
for several languages.
Language | SDK | Sample application
-----|-----|-----|
C# | [smartsheet-csharp-sdk](https://github.com/smartsheet-platform/smartsheet-csharp-sdk)
| [csharp-read-write-sheet](https://github.com/smartsheet-samples/csharp-read-write-sheet)
Java | [smartsheet-java-sdk](https://github.com/smartsheet-platform/smartsheet-java-sdk)
| [java-read-write-sheet](https://github.com/smartsheet-samples/java-read-write-sheet)
Node.js | [smartsheet-javascript-sdk](https://github.com/smartsheet-platform/smartsheet-javascript-sdk)
| [node-read-write-sheet](https://github.com/smartsheet-samples/node-read-write-sheet)
Python | [smartsheet-python-sdk](https://github.com/smartsheet-platform/smartsheet-python-sdk)
| [python-read-write-sheet](https://github.com/smartsheet-samples/python-read-write-sheet)
Ruby | [smartsheet-ruby-sdk](https://github.com/smartsheet-platform/smartsheet-ruby-sdk)
| [ruby-read-write-sheet](https://github.com/smartsheet-samples/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/Columns/Rows/Cells
Sheets are composed of rows, columns, and cells. A cell is identified by the Id
of its row and column. The following table defines these terms and points you
to places in this documentation where you can find more information:
UI Element | Description | More Info
-----|-----|-----|
sheet | A sheet can exist in a user's [Home](../../tag/homeDescription) folder,
in a [folder](../../tag/foldersDescription), or in a [workspace](../../tag/workspacesDescription/).
It is comprised of columns, rows, and cells, and may optionally contain attachments
or discussions. | [Sheet object](tag/sheetsObjects#section/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](../../tag/columnsObjects#section/Column-Object),
[Column types](../../tag/columnsRelated#section/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](tag/rowsObjects#section/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](tag/cellsObjects#section/Cell-Object),
[Cell reference](tag/cellsRelated#section/Cell-Reference)
## Versioning and Changes
Smartsheet will add new functionality and bug fixes to the API over time. Make
sure that your code can handle new JSON properties gracefully. Also, make sure
your code does not depend on the order in which JSON objects are returned, unless
it is explicitly stated in this documentation.
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](#section/API-Basics/Multi-contact-or-Multi-picklist:-Working-with-Complex-Objects)
# Code Walkthrough
## Make Your First API Call
Before you write any code, try executing API requests using a tool like [cURL](https://curl.haxx.se/)
or [Postman](https://www.postman.com/). 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](#section/API-Basics/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](#section/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):
```json
{
"pageNumber": 1,
"pageSize": 100,
"totalPages": 1,
"totalCount": 2,
"data": [{
"id": 6141831453927300,
"name": "My first sheet",
"accessLevel": "ADMIN",
"permalink": "https://app.smartsheet.com/b/home?lx=8enlO7GkdYSz-cHHVus33A",
"createdAt": "2016-01-28T22:02:35Z",
"modifiedAt": "2016-08-09T17:50:06Z"
},
{
"id": 6141831453927300,
"name": "Sheet shared to me",
"accessLevel": "VIEWER",
"permalink": "https://app.smartsheet.com/b/home?lx=8enlO7GkdYSz-cHHVus33A",
"createdAt": "2016-01-28T22:02:35Z",
"modifiedAt": "2016-08-09T17:50:06Z"
}
]
}
```
## How to Read a Sheet Response
Many Smartsheet API operations handle sheets, rows, columns, and cells. Each is
identified by an Id and it is important to understand the relationship between
these objects. Typically you loop through the columns to determine the Id of the
columns you are interested in. Then you loop through the rows and contained cells
to find actual values. The annotated sample response below illustrates these concepts
by calling a very simple sheet called "Employee Roster".
Before you begin, you should already have an access token, which you used in the
exercise above. Use the same access token for this walkthrough.
**Step 1:** The first thing you must have is a sheetId. To find a sheetId through
the UI, with the sheet open, click "Sheet Actions" in the left toolbar and select
"Properties". **NOTE:** use [List Sheets](tag/sheets#operation/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.
```json
{
"id": 6141831453927300, // Sheet Id
"name": "My first sheet",
"columns": [{ // Each Column object associates column Id
// to title and defines the
// column details
"id": 2517104256673668, // Column Id
"index": 0,
"title": "Name",
"type": "TEXT_NUMBER",
"primary": true,
"width": 150
},
{
"id": 7020703884044164, // Next column Id
"index": 1,
"title": "EmployeeId",
"type": "TEXT_NUMBER",
"width": 150
}
],
"rows": [{ // A Row object
"id": 564480076736388, // Row Id
"rowNumber": 1,
"expanded": true,
"createdAt": "2017-05-12T16:52:38Z",
"modifiedAt": "2017-05-22T20:40:14Z",
"cells": [{ // Each row contains an array of cells,
// which have the actual content
"columnId": 2517104256673668,
// The column Id can be interpreted by
// looking at the array of column
// definitions above. That tells you
// this is the "Name" column
"value": "John Doe",
"displayValue": "John Doe"
},
{
"columnId": 7020703884044164,
"value": 12345, // Actual cell value
"displayValue": "12,345"
// How the cell value is displayed in the UI
}
]},
{
"id": 5068079704106884,
"rowNumber": 2,
"siblingId": 564480076736388,
"expanded": true,
"createdAt": "2017-05-12T16:52:38Z",
"modifiedAt": "2017-05-22T20:40:14Z",
"cells": [{
"columnId": 2517104256673668,
"value": "Jane Roe",
"displayValue": "Jane Roe"
},
{
"columnId": 7020703884044164,
"value": 67890,
"displayValue": "67890"
}
]
}
]
}
```
This core hierarchy of Sheet > Column > Row > Cell is essential to working with
the Smartsheet API. As your user's sheets grow in complexity, the responses do
too. This walkthrough has given you some navigational aid in finding the right
value to plug into your API calls. Use the API Reference and the example language
tabs to learn more.
# Error Code List
For an explanation of the logic behind Smartsheet error codes and error handling,
see the [HTTP and REST](#section/API-Basics/HTTP-and-REST) portion of the Introduction.
## 400-Level Error Codes
400-level error codes generally indicate that there is something you should fix
or add to your request before you try the request again.
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
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.
# OAuth Walkthrough
Apps connect to Smartsheet using [OAuth 2.0](https://oauth.net/2/) to authenticate
and authorize users. If you are building an app, this documentation will walk
you through the steps you need to authenticate your users. The Smartsheet [SDKs](#section/API-Basics/SDKs-and-Sample-Code)
contain APIs for OAuth 2.0.
## First Steps
Before you can start using OAuth 2.0 with your app, Smartsheet needs the following
information:
1. You must [register](https://developers.smartsheet.com/register) with Smartsheet
to get a developer account*. The developer account gives you access to "Developer
Tools", which is where you manage your app.
2. In "Developer Tools", complete any required fields in your developer profile.
3. In "Developer Tools", register your app so Smartsheet can assign a client Id
and a client secret to the app.
4. Review the list of access scopes. You'll need to choose which ones your app
needs to get to a user's Smartsheet data, and then ask the user to consent to
that access.
After you've worked through these steps, you'll be ready to implement the [OAuth
Flow](#section/OAuth-Walkthrough/OAuth-Flow).
*Review the [Developer Program Agreement](https://www.smartsheet.com/legal/developer-program-agreement).
## Open Developer Tools
1. Log in to Smartsheet with your developer account.
2. Click the "Account" button in the lower-left corner of your Smartsheet screen,
and then click "Developer Tools".
3. Do one of the following:
* If you need to register an app, click "Create New App".
* If you need to manage an app, click "view/edit" for the app.
## Register Your App Using Developer Tools
1. Log in to Smartsheet with your developer account.
2. Click the "Account" button in the upper-right corner of your Smartsheet screen,
and then click "Developer Tools".
3. In the "Create New App" form, provide the following information:
* Name: the name the user sees to identify your app
* Description: a brief description intended for the user
* URL: the URL to launch your app, or the landing page if not a web app
* Contact/support: support information for the user
* Redirect URL: also known as a callback URL. The URL within your application
that will receive the OAuth 2.0 credentials
After you click "Save", Smartsheet assigns a client Id and secret to your app.
Make a note of these Ids for the next steps; however, you can always look them
up again in "Developer Tools".
## OAuth Flow
Your app must implement a 3-legged OAuth flow to retrieve an access token it can
use to access Smartsheet data on behalf of an end user.
The following diagram has an overview of the OAuth flow:
NOTE: App registration and OAuth flow require HTTPS.
## Access Scopes
To access a user's Smartsheet data, your application must explicitly ask the user
for permission. You do this by using access scopes, which enable your app to communicate
to the user what type of operations it is performing.
Access scopes do not override existing [access-level restrictions](#section/Security/Access-Levels).
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](#section/OAuth-Walkthrough/Access-Scopes) for a complete list.
NOTE: Additional Info:- When you request an authorization code, you
specify all of the access scopes you need for your app. Smartsheet encodes those
permissions into the auth code and subsequent access token.
- Your app must
request at least one access scope, but should only request the scopes necessary.
- Once
your app attains a valid access token, it can execute a [Get Current User](tag/users#operation/get-current-user)
operation, regardless of which access scopes were requested.
## Request an Authorization Code
`GET https://app.smartsheet.com/b/authorize`
`POST https://app.smartsheet.com/b/authorize`
Initiates the process to get authorization from the user.
Smartsheet will redirect this URL to display your app's consent page with an explanation
of the data the app will need access to. This consent page is autogenerated by
Smartsheet based on a combination of the information you registered for your app
and the parameters you send with the request.
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](#section/OAuth-Walkthrough/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
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](#section/OAuth-Walkthrough/OAuth-Error-Types).
## If the User Clicks Deny
If the user clicks "Deny", Smartsheet redirects the user to the callback URL with
the following parameters:
Value | Description |
-----|-----|
**error** | "access_denied".
**state** | The same value for **state** that you sent when you requested the
authorization code.
## Get or Refresh an Access Token
Once you’ve successfully obtained an authorization code, the next step is to exchange
the code for an access token. (Remember, the authorization code expires after
599135 milliseconds.)
Access tokens expire after 604799 seconds, which is approx 7 days. Use the refresh
token to obtain a new access token and a new refresh token. Once you obtain the
new tokens, you must use them in place of the old ones, which are no longer valid.
To get or refresh an access token, see [Refresh Access Token](tag/token#operation/tokens-getOrRefresh).
## OAuth Error Types
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](#section/OAuth-Walkthrough/Access-Scopes).
**unsupported_grant_type** | **grant_type** must equal **authorization_code**
or **refresh_token**.
**unsupported_response_type** | **response_type** must be set to **code**.
# Resources
Please note the following resources:
* [Smartsheet Developer Portal:](https://developers.smartsheet.com) If registering,
use a different email address from your paid Smartsheet account so you can test
the API and make API calls
* Developer Newsletter (subscribe while at the Developer Portal using the "Get
Developer Updates" form)
* Smartsheet
Community
* [Contact us--regular commercial accounts](https://app.smartsheet.com/b/form/739aa75f30ca43a8a22eb53e4da7d409?Origin=com-us)
* [Contact us for Smartsheet Regions-Europe](https://app.smartsheet.com/b/form/739aa75f30ca43a8a22eb53e4da7d409?Origin=com-eu)
* [10000ft API documentation](https://10kft.github.io/10kft-api/)
* [StackOverflow](https://stackoverflow.com/questions/tagged/smartsheet-api) using
the "smartsheet-api" tag
* Review the [Developer Program Agreement](https://www.smartsheet.com/legal/developer-program-agreement)
# Security
The following provides some best practices to consider when working with the Smartsheet
API and any API keys, tokens, or other sensitive information.
## Adding Security by Using OAuth
If your application requires users to be able to login with their own account,
you must implement the full OAuth flow.
At a high level, this involves the following steps:
1. [Register as a Developer](https://developers.smartsheet.com/register) with
Smartsheet so you can get access to the Developer Tools menu.
2. Register your app to get both a clientId and client secret, which you'll need
to store securely. Some best practices suggestions for security are below.
3. Go through the steps in the [OAuth Walkthrough](#section/OAuth-Walkthrough)
once you are ready to request authorization.
NOTE: When using OAuth, be sure to review the [Access Scopes](#section/OAuth-Walkthrough/Access-Scopes)
needed for your app and only request the necessary scopes.
## Access Levels
Sheets, templates, and workspaces have an **accessLevel** attribute that describes
the current user's access level to that object.
This corresponds directly to the sharing and access controls of Smartsheet that
are available through the Smartsheet UI.
The **accessLevel** attribute has one of the following values:
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](#section/OAuth-Walkthrough/Access-Scopes).
Access levels describe the actual permissions a specific user has for a specific
sheet or other resource. Access scopes describe the general categories of access
requested by a third-party app.
## API Key Management
If you've committed code to a repository before implementing these security best
practices, here are some steps to resecure your API keys.
For raw tokens:
1. [Revoke token](tag/token#operation/tokens-delete)
2. Create a [new token](#section/API-Basics/Raw-Token-Requests)
If using OAuth for an integration:
* Work through the [OAuth Walkthrough](#section/OAuth-Walkthrough) to regenerate
client secrets, auth codes, and tokens.
## Source Code and Version control
Never commit API keys to accessible version control systems like GitHub or BitBucket.
Instead, you should:
* Use an app configuration tool suitable for deploying secrets to your app, or
* Use a config file outside of source control, or
* Use environment variables set outside of source control.
If you have mistakenly deployed API keys to a publicly accessible location such
as GitHub, then you should immediately revoke those API keys, revise your application
to use a preferred method of key deployment, and then generate new keys.
If you need to store API keys in a database, consider the following protections:
* Restrict access so API keys are only readable by the owner of the object
* Restrict read privileges to the database table
* Make sure your database or the disk the database is on is set to encrypt data
at rest
NOTE: When using any Smartsheet SDK, you can use the environment variable of SMARTSHEET_ACCESS_TOKEN.
If the access token is null on input to the client builder, the SDK will automatically
pick up the value of that environment variable.
# Smartsheet Gov
Smartsheet Gov has "FedRAMP Authorized" status as part of Federal Risk and Authorization
Management Program (FedRAMP). As an API developer working on a Smartsheet Gov
account, you should be aware of the following differences from the standard API:
* The base URL for each API call is smartsheetgov.com instead of smartsheet.com.
This documentation uses smartsheet.com in *all* examples.
* Smartsheetgov.com uses a separate token from Smartsheet.com.
* Smartsheetgov.com has a restriction on attachment types. Only the following
attachment types are allowed: BOX_COM, FILE, GOOGLE_DRIVE, LINK, or ONEDRIVE.
If you use a Smartsheet SDK, you need to modify the standard config file to point
to smartsheetgov.com. There are instructions specific to each SDK on how to modify
the config file at the following locations:
* [C# SDK](https://github.com/smartsheet-platform/smartsheet-csharp-sdk/blob/master/ADVANCED.md#working-with-smartsheetgovcom-accounts)
* [Java SDK](https://github.com/smartsheet-platform/smartsheet-java-sdk/blob/master/ADVANCED.md#working-with-smartsheetgovcom-accounts)
* [Node.js SDK](https://github.com/smartsheet-platform/smartsheet-javascript-sdk#working-with-smartsheetgovcom-accounts)
* [Python SDK](https://github.com/smartsheet-platform/smartsheet-python-sdk/blob/master/ADVANCED.md#working-with-smartsheetgovcom-accounts)
* [Ruby SDK](https://github.com/smartsheet-platform/smartsheet-ruby-sdk#basic-configuration)
# Smartsheet Regions Europe
Smartsheet Regions Europe is a separate data island. As an API developer working
on a Smartsheet Regions Europe account, you should be aware of the following differences
from the standard API:
* The base URL for each API call is smartsheet.eu instead of smartsheet.com. This
documentation uses smartsheet.com in *all* examples.
* Smartsheet Regions Europe aka Smartsheet EU uses a separate token from Smartsheet.com.
If you use a Smartsheet SDK, you need to modify the standard config file to point
to smartsheet.eu. There are instructions specific to each SDK on how to modify
the config file at the following locations:
* [C# SDK](https://github.com/smartsheet-platform/smartsheet-csharp-sdk/blob/master/ADVANCED.md#working-with-smartsheet-regions-europe-accounts)
* [Java SDK](https://github.com/smartsheet-platform/smartsheet-java-sdk/blob/master/ADVANCED.md#working-with-smartsheet-regions-europe-accounts)
* [Node.js SDK](https://github.com/smartsheet-platform/smartsheet-javascript-sdk#working-with-smartsheet-regions-europe-accounts)
* [Python SDK](https://github.com/smartsheet-platform/smartsheet-python-sdk/blob/master/ADVANCED.md#working-with-smartsheet-regions-europe-accounts)
* [Ruby SDK](https://github.com/smartsheet-platform/smartsheet-ruby-sdk#basic-configuration)
# Troubleshooting
Should you encounter issues with the Smartsheet API while building an integration
using a particular programming language, for example C#, Java, Node.js, Python,
or Ruby, keep the following troubleshooting techniques in mind.
Try executing the same API Request using a tool like [cURL](https://curl.haxx.se/)
or [Postman](https://www.postman.com/). By taking your code out of the equation,
you can isolate troubleshooting to the raw Request / Response.
* If you receive a similar error when you execute the Request using cURL or Postman,
this suggests an issue with the Request format or contents. Once you have the
Request working in cURL or Postman, update your code accordingly.
* If you can execute the Request successfully using cURL or Postman, but not via
your code, this suggests that the Request your code is sending is somehow different
than what you intend. Compare the (successful) Request from cURL or Postman with
the (unsuccessful) Request that your code generates. (See step #2 below.)
Examine the Request that your code is sending (including the HTTP verb, URI, headers,
and Request body) and the Response that it's receiving back from Smartsheet (including
the HTTP status code, headers, and response body).
* If you've implemented Request / Response logging in your application, inspect
the full trace of Request and Response in the log file. Compare the Request that
your application is logging with the (successful) Request from cURL or Postman,
and update your code to correct any discrepancies.
* Alternatively, you may choose to use a tool like [Fiddler](https://www.telerik.com/fiddler)
or [Charles HTTP Proxy](https://www.charlesproxy.com/) to inspect the full trace
of Request and Response as it goes across the wire. Compare the Request trace
that your application generates with the (successful) Request from cURL or Postman,
and update your code to correct any discrepancies.
Check for capitalization errors. **NOTE:** URL endpoints are all lower case, while
object properties and query parameters are camelCase.
# Work at Scale
## Bulk Operations
The Smartsheet API supports a number of bulk operations that can operate on multiple
objects. Unlike single-object operations, bulk operations allow you to create,
update, or delete
multiple objects in a single request. For example, if you want to update 10 rows
within a sheet, do so using a single [Update Rows](tag/rows#operation/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](tag/commonObjects/#section/Result-Object)
returned contains either a single object or an array. An example optional bulk
operation is [POST /favorites](tag/favorites#operation/add-favorite): you can
pass in a single [Favorite object](tag/favoritesObjects#section/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](tag/commonObjects#section/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](../../tag/commonObjects#section/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](tag/commonObjects#section/BulkItemFailure-Object)
that contains an item for each object in the request that failed to be added/updated/deleted.
## Paging
The Smartsheet API contains a number of index endpoints (typically denoted in
the documentation with titles beginning with "Get All" or "List") which return
arrays of objects.
Examples include `GET` [/users](tag/users#operation/list-users), [/sheets](tag/sheets#operation/list-sheets),
[/sheets/{sheetId}/columns](tag/columns#operation/columns-listOnSheet), 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.
## Rate Limiting
**Handle "Rate limit exceeded" Error**
To prevent abuse and undue stress on the Smartsheet servers, the API has a rate
limiting feature (sometimes called throttling) that restricts users to **300**
requests per minute per access token.
Certain resource intensive operations, such as attaching a file and getting cell
history, count as 10 requests.
Smartsheet reserves the right to enforce this limit depending on the load on our
systems.
If and when the limit is enforced, any requests that exceed this limit are rejected
with an **429** HTTP status code, along with the following JSON response body:
```json
{
"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](https://en.wikipedia.org/wiki/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](tag/rows#operation/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](#section/Work-at-Scale/Bulk-Operations)
(for example, [Update Rows](tag/rows#operation/update-rows) or [Add Columns](tag/columns#operation/columns-addToSheet).
**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](#section/Error-Code-List/400-Level-Error-Codes).
tags:
- name: alternateEmailAddress
x-displayName: Methods
- name: alternateEmailAddressDescription
x-displayName: Alternate Email Addresses Basics
description: >
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:
* Add Group Members
* Add User
* Create Update Request
* Share Report
* Share Sheet
* Share Workspace
Attempting to specify a user's alternate email address for any of the above operations
results in an error.
- name: alternateEmailAddressObjects
x-displayName: Objects
description: |
# AlternateEmail Object
- name: attachments
x-displayName: Methods
- name: attachmentsDescription
x-displayName: Attachments Basics
description: >
Attachments can exist on a [comment](../../tag/commentsDescription/) (that
is, within a discussion), on a [row](../../tag/rowsDescription), or on a
[sheet](../../tag/sheetsDescription).
# Post an Attachment
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](#section/Post-an-Attachment/Simple-Uploads) 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](../../tag/attachments#operation/attachments-attachToSheet),
[attach a file to a row](../../tag/attachments#operation/row-attachments-attachFile),
or [attach a file to a comment](../../tag/attachments#operation/attachments-attachToComment).
A [multipart upload](#section/Post-an-Attachment/Multipart-Uploads) 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](../../tag/comments#operation/comments-create)
that contains a single file attachment or to [add a new discussion to a sheet](../../tag/discussions#operation/discussions-create)
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.
## Multipart Uploads
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:- **form-data**
- **name="*partname*"**
- **filename="*filename*"**
(only required for file parts)
NOTE: Values specified in the Content-Disposition
header must be URL-encoded.
**Content-Type** | The content type of the part: **application/json** for JSON
objects, or the applicable MIME type for file parts
The last part in the request must be followed by the boundary string, followed
by two hyphens.
The documentation for each operation that supports multipart uploads specifies
the number and names of parts that are expected for the operation.
File parts must have the part name "file", and documentation for operations which
allow for JSON object parts specify the required part name for the JSON part.
The following example shows a multipart upload request that creates a comment
containing the specified text and file attachment:
`POST https://api.smartsheet.com/2.0/sheets/4509093797881732/discussions/2889925487028100/comments`
`Authorization: Bearer ll352u9jujauoqz4gstvsae05`
`Content-Length: 29008`
`Content-Type: multipart/form-data; boundary=----gU8h01zAAp3LagBr`
`------gU8h01zAAp3LagBr`
`Content-Disposition: form-data; name="comment"`
`Content-Type: application/json`
`{ "text": "Please review the attached image." }`
`------gU8h01zAAp3LagBr`
`Content-Disposition: form-data; name="file"; filename="picture.jpg"`
`Content-Type: image/jpeg`
*< Binary content for file >*
`------gU8h01zAAp3LagBr--`
NOTE: Most programming languages have libraries that can be used to assemble multipart
requests.
## Simple Uploads
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: `$ ls -l ProgressReport.docx`
`5463
ProgressReport.docx`
**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.
- name: attachmentsObjects
x-displayName: Objects
description: >
# Attachment Object
# URLAttachmentRequest Object
- name: automationRules
x-displayName: Methods
- name: automationRulesDescription
x-displayName: Automation Rules Basics
description: >
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.
- name: automationRulesObjects
x-displayName: Objects
description: |
# AutomationRule Object
# AutomationAction Object
- name: automationRulesRelated
x-displayName: Related Items
description: >
# Disabled Reasons for Automation Rules
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.
- name: cellImages
x-displayName: Methods
- name: cellImagesDescription
x-displayName: Cell Images Basics
description: |
A cell image is an image that has been uploaded to a cell within a sheet.
- name: cellImagesObjects
x-displayName: Objects
description: |
# Image Object
# Image Url Object
# Image Url Map Object
- name: cells
x-displayName: Methods
- name: cellsDescription
x-displayName: Cells Basics
description: |
A collection of cells comprises each row in a sheet.
- name: cellsObjects
x-displayName: Objects
description: |
# Cell Object
# CellHistory Object
# CellLink Object
# Duration Object
# Hyperlink Object
# ObjectValue Object
# Predecessor Object
# PredecessorList Object
- name: cellsRelated
x-displayName: Related Items
description: >
# Cell Links
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](../../tag/cellsObjects#section/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 Reference
## Cell Value Representation
[Cell objects](../../tag/cellsObjects#section/Cell-Object) 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:
[Help with Project Columns](https://help.smartsheet.com/articles/765737-project-sheet-columns-start-date-end-date-duration-complete-and-predecessors)
Column Type | Possible Types for Cell.value | Returns Cell.displayValue?
------------|-------------------------------|---------------------------
ABSTRACT_DATETIME | string: a project date and time in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)
format, or a free-form text value.
number: see [Dates and Times](../../#section/API-Basics/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](https://en.wikipedia.org/wiki/ISO_8601) format,
or a free-form text value.
number: see [Dates and Times](../../#section/API-Basics/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.
* For predecessors, it provides a more "programmer friendly" format for assembling
predecessors. To update a cell's predecessors, set **objectValue** to a
[PredecessorList object](../../tag/cellsObjects#section/PredecessorList-Object)
containing [Predecessor objects](../../tag/cellsObjects#section/Predecessor-Object).
* For multi-contact or multi-picklist details, use both a level query parameter
*and* an **include=objectValue** query to see email addresses rather than display
names or to see multi-picklist values.
## Cell Value Parsing
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](../../#section/Error-Code-List/400-Level-Error-Codes).
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](../../tag/cellsObjects#section/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](../../#section/API-Basics/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](#section/Cell-Reference/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](#section/API-Basics/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](../../tag/serverInfoDescription) 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](../../tag/cellsRelated#section/Cell-Reference).
**MULTI_PICKLIST**
Value | Description |
-----|-----|
N/A | Set using the **objectValue** attribute for the Cell object, which is inherently
strict. See [Cell Reference](../../tag/cellsRelated#section/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](../../tag/cellsRelated#section/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](../../#section/Error-Code-List/400-Level-Error-Codes).
If using lenient parsing, the value is silently converted to text.
## Contact List Columns
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:
* If **displayValue** is non-null and non-empty, the Smartsheet cell displays
the value provided.
* If **displayValue** is an empty string, the Smartsheet cell displays the email
address.
* If **displayValue** is null or absent, Smartsheet makes a best guess effort
at filling it in with a contact’s name based on the email address.
# Hyperlinks
You can create and modify [hyperlinks](../../tag/cellsObjects#section/Hyperlink-Object)
by using any API operation that creates or updates cell data.
When creating or updating a hyperlink, **cell.value** may be set to a string value
or null.
If null, the cell's value is derived from the hyperlink:
* If the hyperlink is a URL link, the cell's value is set to the URL itself.
* If the hyperlink is a dashboard, report, or sheet link, the cell's value is
set to the dashboard, report, or sheet name.
## Images in Cells
For details about working with images in cells, see [Cell Images](../../tag/cellImagesDescription).
- name: columns
x-displayName: Methods
- name: columnsDescription
x-displayName: Columns Basics
description: |
A column is a component of a sheet or report.
- name: columnsObjects
x-displayName: Objects
description: |
# Column Object
# ContactOption Object
- name: columnsRelated
x-displayName: Related Items
description: >
# Column Types
Smartsheet supports the following standard column types, which are represented
in a [Column object](../../tag/columnsObjects#section/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](../../tag/columnsObjects#section/ContactOption-Object)
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:
- Created (Date) (**Column.systemColumnType** = **CREATED_DATE**)
- Modified
(Date) (**Column.systemColumnType** = **MODIFIED_DATE**)
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](../../tag/cellsObjects#section/PredecessorList-Object).
**Only for dependency-enabled project sheets**
Text/Number | **TEXT_NUMBER** |
NOTE: See the [Cell Reference](../../tag/cellsRelated#section/Cell-Reference)
section for information on getting and setting cell values for the different column
types.
## Symbol Columns
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.
## System Columns
In addition to the standard column types and symbols, Smartsheet has a number
of system columns, which represent data that is
filled in by Smartsheet and whose values cannot be changed by the user. These
columns are represented with standard
[column types](../../tag/columnsRelated#section/Column-Types), with the **[Column.systemColumnType](../../tag/columnsObjects#section/Column-Object)**
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](../../tag/commonObjects#section/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
- name: comments
x-displayName: Methods
- name: commentsDescription
x-displayName: Comments Basics
description: >
A discussion is a container for a number of individual comments in a
threaded conversation. For more details, see the
[Discussion](../../tag/discussionsDescription) section.
This section describes operations on an *individual* comment within a discussion
thread.
* To retrieve all discussions and comments for an entire sheet, use [List Discussions](../../tag/discussions#operation/discussions-list)
with the query parameter **include=comments**.
* To retrieve all discussions and comments associated with a row, use [List Row
Discussions](../../tag/discussions#operation/row-discussions-list) with the
query parameter **include=comments**.
- name: commentsObjects
x-displayName: Objects
description: |
# Comment Object
- name: commentsRelated
x-displayName: Related Items
description: >
A comment can contain one or more attachments.
# Comment Attachments
For details about working with a comment's attachments, see [Attachments](../../tag/attachmentsDescription).
- name: commonObjects
x-displayName: Other Objects
description: >
# AutoNumberFormat Object
# BulkItemFailure Object
# ContainerDestination Object
# Currency Object
# Error Object
# FontFamily Object
# FormatTables Object
# IndexResult Object
# Result Object
- name: contacts
x-displayName: Methods
- name: contactsDescription
x-displayName: Contacts Basics
description: >
A contact is a user's personal contact in Smartsheet (as described in the
Help Center article, [Managing
Contacts](https://help.smartsheet.com/articles/796143-managing-contacts)).
- name: contactsObjects
x-displayName: Objects
description: |
# Contact Object
- name: crossSheetReferences
x-displayName: Methods
- name: crossSheetReferencesDescription
x-displayName: Cross-sheet References Basics
description: >
To create a formula that references data in another sheet, you must first
create a cross-sheet
reference between the detail sheet and the source sheet. That reference must also
define the cell range.
Once you have created the cross-sheet reference, you can use the reference name
in any formula on the detail sheet.
To create the formula, use Add Rows or Update Rows. Cross-sheet references that
are not used by any formula are
automatically deleted after two hours.
- name: crossSheetReferencesObjects
x-displayName: Objects
description: |
# CrossSheetReference Object
- name: dashboards
x-displayName: Methods
- name: dashboardsDescription
x-displayName: Dashboards Basics
description: >
Smartsheet dashboards are a collection of widgets that can contain data
from a variety of different data sources (for example, sheets, reports, or
custom data). Dashboards were once called Sights(TM) and this name is
still present in object names, endpoint paths, and other places.
- name: dashboardsObjects
x-displayName: Objects
description: >
# Dashboard Object
# DashboardPublish Object
# Widget Object
# CellLinkWidgetContent Object
# CellDataItem Object
# ChartWidgetContent Object
# ImageWidgetContent Object
# ReportWidgetContent Object
# RichTextWidgetContent Object
# SelectionRange Object
# ShortcutDataItem Object
# ShortcutWidgetContent Object
# TitleWidgetContent Object
# WebContentWidgetContent Object
# WidgetHyperlink Object
- name: discussions
x-displayName: Methods
- name: discussionsDescription
x-displayName: Discussions Basics
description: >
A discussion is a container for a collection of individual
[comments](../commentsDescription) within a single thread. A discussion
can exist on a [row](../rowsDescription) or a
[sheet](../sheetsDescription).
In the UI, Smartsheet creates a discussion to contain each top-level comment and
subsequent replies into a single thread.
Using the API, you can only add a comment to a discussion. If the discussion doesn't
already exist, you must create it first.
- name: discussionsObjects
x-displayName: Objects
description: |
# Discussion Object
- name: discussionsRelated
x-displayName: Related Items
description: >
A discussion is a collection of one or more comments, each of which may
contain attachments.
# Discussion Attachments
For details about working with the attachments within a discussion, see [Attachments](../../tag/attachmentsDescription).
# Discussion Comments
For details about working with a discussion's comments, see [Comments](../../tag/commentsDescription).
- name: events
x-displayName: Methods
- name: eventsDescription
x-displayName: Events Basics
description: >
The following section describes the specific event types and payloads
returned from the Smartsheet Events API.
With Event Reporting, you can programmatically retrieve events that are occurring
in your Smartsheet organization account. Examples of events are create, update,
load, and delete of sheets, reports, dashboards, attachments, and users. Note:
while the current list of events covers most of Smartsheet functionality, new
events will be added to the list as Smartsheet introduces new functionality.
Some actions in Smartsheet are performed by system components. Therefore, the
userId property in some response payloads refers to a system user and not to a
regular user. For example, the Smartsheet Events API shows 5629504736520068 as
the userId when an anonymous user accesses a sheet that is published for anyone.
The list of system users is displayed below. New system userIds may be incorporated
to this list as new features and subsystems are incorporated to Smartsheet:
System user | Description |
-----|-----|
1688855062570884 | Data accessed/modified by Skype action (only possible if Smartsheet
account is connected to Skype) |
2814754969413508 | Data accessed/modified by Trello import action (only possible
if Smartsheet account is connected to Trello) |
3377704922834820 | Data accessed/modified due to Smartsheet cell-link |
3940654876256132 | Data accessed/modified by the Smartsheet Automation system
|
5066554783098756 | Access to object published to any user in the Smartsheet organization
account |
5629504736520068 | Access to Smartsheet object published to anyone |
6192454689941380 | Data accessed/modified by the Smartsheet Notification system
|
7881304550205316 | Data accessed/modified by Smartsheet Form submission |
See Event
Reporting reference documentation for details on each event type.
See [Authentication and Access Tokens](../../#section/API-Basics/Authentication-and-Access-Tokens)
for more information.
NOTE: Event Reporting is a premium add-on for Enterprise and Premier plans only.
For details on the Enterprise and Premier plans, see our Pricing
page.
- name: eventsObjects
x-displayName: Objects
description: |
# Event Object
# StreamResult Object
- name: favorites
x-displayName: Methods
- name: favoritesDescription
x-displayName: Favorites Basics
description: >
Smartsheet allows users to "star" dashboards, folders, reports, sheets,
workspaces, and other objects on their Home tab to mark them as favorites.
These API operations allow you to access the user's favorite API-supported objects,
as well as create and delete favorites.
NOTE: For documentation purposes, "favoriteType" is a placeholder ENUM for the
various types of UI elements you can flag as a favorite. In sample code, when
you see "{favoriteType}", just replace it with one of the following values:
* dashboard or dashboards (aka Sight or Sights)
* folder or folders
* report or reports
* sheet or sheets
* template or templates
* workspace or workspaces
- name: favoritesObjects
x-displayName: Objects
description: |
# Favorite Object
- name: folders
x-displayName: Methods
- name: foldersDescription
x-displayName: Folders Basics
description: >
A folder can exist in a user's **Sheets** folder
([Home](../../tag/homeDescription)), in a
[folder](../../tag/foldersObjects), or in a
[workspace](../../tag/workspacesObjects).
- name: foldersObjects
x-displayName: Objects
description: |
# Folder Object
- name: groupMembers
x-displayName: Methods
- name: groupMembersDescription
x-displayName: Group Members Basics
description: >
A group member is a user that belongs to a
[group](../../tag/groupsDescription).
- name: groupMembersObjects
x-displayName: Objects
description: |
# Group Member Object
- name: groups
x-displayName: Methods
- name: groupsDescription
x-displayName: Groups Basics
description: >
A group is a collection of [group
members](../../tag/groupMembersDescription).
- name: groupsObjects
x-displayName: Objects
description: |
# Group Object
- name: home
x-displayName: Methods
- name: homeDescription
x-displayName: Home Basics
description: >
In the Smartsheet UI, the "Home" tab shows all objects a user has access
to, including dashboards (also called Sights in the API), folders,
reports, sheets, templates, and workspaces.
- name: homeObjects
x-displayName: Objects
description: |
# Home Object
- name: homeRelated
x-displayName: Related Items
description: >
# Home Folders
For details about working with folders in the user's **Sheets** folder (that is,
at the Home level), see [Folders](../../tag/foldersDescription).
# Home Sheets
For details about working with sheets in the user's **Sheets** folder (that is,
at the Home level), see [Sheets](../../tag/foldersDescription).
- name: import
x-displayName: Methods
- name: importDescription
x-displayName: Import Basics
description: |
Import CSV or XLSX data into a new sheet.
- name: proofs
x-displayName: Methods
- name: proofsDescription
x-displayName: Proofs Basics
description: >
A proof is a container that holds attachments and comments. Limited to one
proof and its versions per row.
A sheet can have multiple proofs.
- name: proofsObjects
x-displayName: Objects
description: |2
# Proof Object
# ProofRequest Object
# ProofRequestAction Object
- name: reports
x-displayName: Methods
- name: reportsDescription
x-displayName: Reports Basics
description: >
A report is a filtered view of the data from one or more sheets. Like a
sheet, a report is comprised of columns, rows, and cells, and may
optionally contain attachments and discussions.
- name: reportsObjects
x-displayName: Objects
description: |
# Report Object
# Report Cell Object
# Report Column Object
# Report Row Object
# Report Publish Object
# Scope Object
- name: reportsRelated
x-displayName: Related Items
description: >
A report is comprised of columns, rows, and cells, and may optionally
contain attachments and discussions.
# Report Attachments
For details about working with a report's attachments, see [Attachments](../../tag/attachmentsDescription).
# Report Cells
For details about working with a report's cells, see [Cells](../../tag/cellsDescription).
# Report Columns
For details about working with a report's columns, see [Columns](../../tag/columnsDescription).
# Report Discussions
For details about working with a report's discussions, see [Discussions](../../tag/discussionsDescription).
# Report Rows
For details about working with a report's rows, see [Rows](../../tag/rowsDescription).
- name: rows
x-displayName: Methods
- name: rowsDescription
x-displayName: Rows Basics
description: >
A row is a component of a sheet or report. Each row is composed of a
collection of cells, and may optionally contain discussions or
attachments.
- name: rowsObjects
x-displayName: Objects
description: >
# Row Object
# CopyOrMoveRowDestination Object
# CopyOrMoveRowDirective Object
# CopyOrMoveRowResult object
# RowMapping Object
- name: rowsRelated
x-displayName: Related Items
description: >
A row is comprised of a collection of cells, and may optionally contain
attachments and discussions.
# Row Attachments
For details about working with a row's attachments, see [Attachments](../../tag/attachmentsDescription).
# Row Cells
For details about working with a row's cells, see [Cells](../../tag/cellsDescription).
For details about working with images in cells, see [Cell Images](../../tag/cellImagesDescription).
# Row Discussions
For details about working with a row's discussions, see [Discussions](../../tag/discussionsDescription).
# Row Include Flags
Endpoints which return rows (for example, [Get Sheet](../../tag/sheets#operation/getSheet),
[Get Row](../../tag/rows#operation/row-get)) support the optional **include**
query string parameter. If specified, the value of the **include** parameter is
a comma-delimited list of flags that indicate additional attributes to be included
in each [Row object](../../tag/rowsObjects#section/Row-Object) within the response.
Include Flag | Description |
-------------|-------|
**attachments** | Includes row **attachments** array.
To include discussion
attachments, both **attachments** and **discussions** must be present in the include
list.
**columnType** | Includes **columnType** attribute in the row's [cells](../../tag/cellsObjects#section/Cell-Object)
indicating the type of the column the cell resides in.
**discussions** | Includes row **discussions** array.
To include discussion
attachments, both **attachments** and **discussions** must be present in the include
list.
**filters** | Includes **filteredOut** attribute indicating if the row should
be displayed or hidden according to the sheet's filters.
**format** | Includes **format** attribute on the row, its cells, or summary
fields. See [Formatting](../../#section/API-Basics/Formatting).
**objectValue** | Includes **objectValue** attribute on cells containing values.
For more information see [Cell Reference](../../tag/cellsRelated#section/Cell-Reference).
**rowPermalink** | Includes **permalink** attribute that represents a direct link
to the [row](../../tag/rowsObjects#section/Row-Object) in the Smartsheet application.
**rowWriterInfo** | **DEPRECATED** Includes **createdBy** and **modifiedBy** attributes
on the row, indicating the row's creator, and last modifier.
**writerInfo** | Includes **createdBy** and **modifiedBy** attributes on the row
or summary fields, indicating the row or summary field's creator, and last modifier.
# Specify Row Location
When you [add a row](../../tag/rows#operation/rows-addToSheet), the default behavior
is for Smartsheet to put the new row at the bottom of the sheet. And when you
[update a row](../../tag/rows#operation/update-rows), the default behavior is
to keep the row where it is. It is not necessary to use a location-specifier attribute
if you want the default behavior.
To specify a location for new or updated rows other than the defaults, use the
table below for reference. The table details possible row locations and provides
JSON examples to help you construct one or more [Row objects](../../tag/rowsObjects#section/Row-Object)
with location-specifier attributes.
Note the following restrictions:
* Use only one location-specifier attribute per request, unless you use **parentId**
and **toBottom** or **siblingId** and **above**.
* If you specify multiple rows in the request, all rows must have the same location-specifier
attributes.
* If you specify the **parentId** attribute, you cannot also specify the **siblingId**
attribute.
* If you specify the **siblingId** attribute, you cannot also specify the **parentId**,
**toTop**, or **toBottom** attributes.
* If you want to indent or outdent multiple rows, use the **parentId** attribute.
Destination | Row Attributes | Examples |
-------|--------|--------|
Top of a sheet | **toTop** | ```("toTop": true}```
Bottom of a sheet | **toBottom** | ```("toBottom": true}```
Top of an indented section a.k.a., first child row | **parentId** | ```("parentId":
8896508249565060}```
Bottom of an indented section a.k.a., last child row | **parentId** +
**toBottom**
| ```{"parentId": 8896508249565060, "toBottom": true}```
Below a specific row, at the same indent level | **siblingId** | ```{"siblingId":
8896508249565060}```
Above a specific row, at the same indent level | **siblingId** +
**above**
| ```{"siblingId": 8896508249565060, "above": true}```
Indent one existing row, must have a value of "1" | **indent** | ```{"indent":
1}```
Outdent one existing row, must have a value of "1" | **outdent** | ```{"outdent":
1}```
- name: search
x-displayName: Methods
- name: searchDescription
x-displayName: Search Basics
description: >
Search a specific sheet or search across all sheets that a user can access.
- name: searchObjects
x-displayName: Objects
description: |
# Search Result Object
# Search Result Item Object
- name: sendViaEmail
x-displayName: Methods
description: >
The methods for sending via email rely on the type of object you want to
send.
# Send Report
For details about sending a report via email, see [Send Report via Email](../../tag/reports#operation/sendReportViaEmail).
# Send Rows
For details about sending rows via email, see [Send Rows via Email](../../tag/rows#operation/rows-send).
# Send Sheet
For details about sending a sheet via email, see [Send Sheet via Email](../../tag/sheets#operation/sheet-send).
# Send Update Request
For details about sending an update request via email, see [Create an Update Request](../../tag/updateRequests#operation/updaterequests-create).
- name: sendViaEmailDescription
x-displayName: Send via Email Basics
description: |
Send a report, row, sheet, or update request via email.
- name: sendViaEmailObjects
x-displayName: Objects
description: |
# Email Object
# Format Details Object
# Recipient Object
# Row Email Object
# Multi Row Email Object
# Sheet Email Object
- name: serverInfo
x-displayName: Methods
- name: serverInfoDescription
x-displayName: Server Info Basics
description: >
For developer convenience, the Smartsheet API provides access to
application constants.
- name: serverInfoObjects
x-displayName: Objects
description: |
# Server Info Object
- name: sharing
x-displayName: Methods
- name: sharingDescription
x-displayName: Sharing Basics
description: >
Use the *Sharing* operations to control sharing of dashboards, reports,
sheets, and workspaces.
- name: sharingObjects
x-displayName: Objects
description: |
# Share Object
- name: sheetSummary
x-displayName: Methods
- name: sheetSummaryDescription
x-displayName: Sheet Summary Basics
description: >
A sheet summary allows users to define, organize, and report on custom
project and business metadata. Sheet summary is only available to
customers with business or enterprise plans.
- name: sheetSummaryObjects
x-displayName: Objects
description: |
# Sheet Summary Object
# Summary Field Object
- name: sheets
x-displayName: Methods
- name: sheetsDescription
x-displayName: Sheets Basics
description: >
A sheet can exist in a user's **Sheets** folder
([Home](../../tag/homeDescription)), in a
[folder](../../tag/foldersDescription), or in a
[workspace](../../tag/workspacesDescription). It is comprised of columns,
rows, and cells, and may optionally contain attachments and discussions.
- name: sheetsObjects
x-displayName: Objects
description: >
# Sheet Object
# Criteria Object
# Filters Object
# ProjectSettings Object
# SheetPublish Object
# SheetUserPermissions Object
# SheetUserSettings Object
# SortCriterion Object
# SortSpecifier Object
# Source Object
- name: sheetsRelated
x-displayName: Related Items
description: >
A sheet is comprised of columns, rows, and cells, and may optionally
contain attachments and discussions.
# Sheet Attachments
For details about working with a sheet's attachments, see [Attachments](../../tag/attachmentsDescription).
# Sheet Cells
For details about working with a sheet's cells, see [Cells](../../tag/cellsDescription).
For details about working with images in cells, see [Cell Images](../../tag/cellImagesDescription).
# Sheet Columns
For details about working with a sheet's columns, see [Columns](../../tag/columnsDescription).
# Sheet Discussions
There are two ways to get discussion-related information for a sheet:
Operation | Returns
----------|----------|
[Get Sheet](../../tag/sheets#operation/getSheet)
(with **include** parameter
value **discussions**) | Response does not contain the comments that comprise
each discussion.
[List Discussions](../../tag/discussions#operation/discussions-list)
(with
**include** parameter value **comments**) | Response contains the comments that
comprise each discussion.
For more information about working with a sheet's discussions, see [Discussions](../../tag/discussionsDescription).
# Sheet Rows
For details about working with a sheet's rows, see [Rows](../../tag/rowsDescription).
- name: templates
x-displayName: Methods
- name: templatesDescription
x-displayName: Templates Basics
description: >
A template can be used to create a sheet, as described in [Create Sheet
from Template](../../tag/sheets#operation/create-sheet-in-folder).
- name: templatesObjects
x-displayName: Objects
description: |
# Template Object
- name: token
x-displayName: Token Methods
- name: tokenDescription
x-displayName: Token Basics
description: >
The Smartsheet API utilizes OAuth 2.0 for authentication and
authorization. An Authorization HTTP header containing an access token is
required to authenticate all API requests except for the requests to GET
Access Token or Refresh Access Token. For more information, see
Authentication.
- name: tokenObjects
x-displayName: Token Objects
description: |
# Token Object
- name: updateRequests
x-displayName: Methods
- name: updateRequestsDescription
x-displayName: Update Requests Basics
description: >
Send update requests to get updated by any collaborator on key rows,
regardless of whether they have a Smartsheet account or are shared to the
sheet.
- name: updateRequestsObjects
x-displayName: Objects
description: |
# UpdateRequest Object
# SentUpdateRequest Object
# Schedule Object
- name: users
x-displayName: Methods
- name: usersDescription
x-displayName: Users Basics
description: >
Users are typically defined by the organization account, and then role
within the organization, for example admin.
- name: usersObjects
x-displayName: Objects
description: |
# User Object
# User Profile Object
# Account Object
# AlternateEmail Object
- name: webhooks
x-displayName: Methods
- name: webhooksDescription
x-displayName: Webhooks Basics
description: >
# Intro to Webhooks
At a high-level, it works like this:
1. Your application subscribes to [callbacks](#section/Webhook-Callbacks/Event-Callbacks).
First,
subscribe to event notifications (callbacks) by creating one or more webhooks. You
can create a webhook manually via the API or have your application create a webhook
dynamically. Each webhook must specify:
* Which Smartsheet object to monitor for events
* Which events in that object should trigger a callback
* The HTTPS URL (that is, "callback URL") where Smartsheet should send callbacks
when any of the specified events occur within the scope of the specified Smartsheet
object. (NOTE: Smartsheet webhooks do not support callbacks to servers
using self-signed certificates)
Webhook examples in plain English:
* "When any changes occur in Sheet_A, send a callback to https://www.example.com/abc"
* "When a new row is added to Sheet_B, send a callback to https://www.example.com/def"
* "When a cell value is changed in Sheet_C, send a callback to https://www.example.com/ghi"
2. When any of the specified events occur within an object that is being monitored
by a webhook, Smartsheet sends an HTTP POST (that is, "callback") to the
callback URL that is associated with the webhook.
* NOTE: The callback payload is a "skinny" payload -- it indicates which objects
changed and the type of events that occurred, but does not contain any data from
the objects themselves.
3. Your application receives, acknowledges, and processes callbacks.
Your
application receives the HTTP POST, acknowledges the callback by
responding with HTTP status 200, and processes the callback. Because the callbacks
are "skinny", make one or more requests to the Smartsheet API to retrieve the
actual data associated with the change.
## Webhook Management
Use the Smartsheet API to create and manage webhooks. See [Webhooks API Reference](#tag/webhooksDescription)
for details about the related API operations.
## Webhook Ownership & Access
Webhooks can be created and managed via [Direct API Access](../../tag/webhooksDescription)
or by a [third-party app](#section/Third-party-App-Development).
A webhook that is created via Direct API Access:
* is owned by the user who created it
* can be managed only by the user who created it
* is not affected if the access token that was used to create it is revoked, as
long as the user remains active
A webhook that is created by a [third-party app](#section/Third-party-App-Development):
* is owned by the user who authorized the third-party app (and is associated with
the third-party app)
* can be managed by the third-party app (as long as it maintains authorization)
or by the user who owns it
* is permanently disabled if the third-party app's permissions are revoked
## Webhook Scope & Events
A webhook monitors the specified **scope** for the specified **events**.
A [Webhook object's](../../tag/webhooksObjects#section/Webhook-Object) **scope**
attribute indicates the scope of the subscription. It is specified when [creating
a webhook](../../tag/webhooksDescription#section/Creating-a-Webhook), and cannot
subsequently be changed.
* Currently, **sheet** is the only supported value for the **scope** attribute.
However, you can set an array of columns as a **subscope** if you want to limit
the webhook to specific columns.
A [Webhook object's](../../tag/webhooksObjects#section/Webhook-Object) **event**
attribute indicates the set of events that a webhook is subscribed to (that is,
which events trigger a callback).
* Events are represented as a dot-separated string in the format "*object*.*event*",
where an asterisk (*) can be used to represent "all objects" or "all events".
* Currently, *.* is the only supported value for the **events**
attribute. This indicates a subscription to all objects in the scope, and all
events for those objects.
NOTE: When a row is deleted on a sheet, even if you are using a subscope
to monitor columns only and the cell in that column for that row is empty, you
will receive a "row.deleted" event.
## Example
Consider a [Webhook object](../../tag/webhooksObjects#section/Webhook-Object)
with the following attribute values:
* **scopeObjectId** = 12345678901234
* **scope** = "sheet"
* **events** = "*.*"
This webhook monitors the specified sheet (id: 12345678901234) for all types of
events. For example, if a row is added to the sheet, cell values are updated in
the sheet, a column is deleted from the sheet, etc., a callback is sent to the
webhook's **callbackUrl**.
# Creating a Webhook
An API client can create a webhook by using the [Create Webhook](../../tag/webhooks#operation/createWebhook)
operation. A newly created webhook is disabled by default.
After successfully creating a webhook, the API client must subsequently initiate
and complete the [verification process](../../tag/webhooksDescription#section/Creating-a-Webhook/Webhook-Verification)
before the webhook is enabled.
The following diagram illustrates the process of creating and enabling a webhook.
## Step-by-Step:
The process occurs synchronously:
1. API client submits a [Create Webhook](../../tag/webhooks#operation/createWebhook)
request.
2. Smartsheet creates the webhook, but does not initially enable the webhook (**enabled:
false** and **status: "NEW_NOT_VERIFIED"**).
3. To initiate the verification process, the API client submits an [Update Webhook](../../tag/webhooks#operation/updateWebhook)
request to specify **enabled: true**. (**NOTE:** The API client does not receive
a response to this request until the verification process (steps 4 and 5) has
completed.)
4. When Smartsheet receives the request to enable the webhook, it sends a [verification
request](#section/Creating-a-Webhook/Webhook-Verification) to the subscriber (that
is, to the **callbackUrl** that the API client specified in the Create Webhook
request).
The request specifies a unique random value in the **Smartsheet-Hook-Challenge**
header and contains only **challenge** and **webhookId** in the request body.
The **challenge** value is a repeat of the header value for API clients that don't
interpret header values.
5. The subscriber responds to the verification request by echoing back the same
unique random value in the **Smartsheet-Hook-Response** header of the response.
For API clients that don't interpret header values, you can also send a JSON body
with a **smartsheetHookResponse** attribute and the same value that would have
been in the header.
6. Once the subscriber has successfully acknowledged the verification request,
Smartsheet enables the webhook and responds to the API client's Update Webhook
request to confirm that the webhook has been enabled (**enabled: true** and **status:
"ENABLED"**).
## Webhook Verification
When an API client attempts to enable a webhook, Smartsheet sends a verification
request to the webhook's **callbackUrl** to verify that the subscriber expects
and is able to successfully receive callbacks.
The request specifies a unique random value in the **Smartsheet-Hook-Challenge**
header and contains a JSON object in the request body with only **challenge**
and **webhookId** attributes in the request body. The **challenge** attribute
is a repeat of the header value for API clients that don't interpret header values.
* To verify the webhook, the subscriber's response to the verification request
must return a 200 HTTP status code and must echo back the same unique random value
in the **Smartsheet-Hook-Response** header of the response or with a JSON **smartsheetHookResponse**
attribute. Once Smartsheet receives this verification response, the webhook is
enabled (**enabled: true** and **status: "ENABLED"**).
* If the subscriber does not successfully respond to the verification request,
the webhook remains disabled (**enabled: false** and **status: "DISABLED_VERIFICATION_FAILED"**).
When a webhook is initially [created through the API](#operation/createWebhook),
the response contains the webhook's Id. If you wish to guarantee that your server
only receives callbacks for webhooks that you created,
you can check the verification request's **webhookId** attribute against your
list of created webhook Ids. If the Id is not in the list, return a response
with a non-200 status code (for example, 403 Forbidden),
and the webhook that initiated the verification request is disabled as described
above.
NOTE: IMPORTANT: ONGOING VERIFICATION. Once a webhook has been enabled,
Smartsheet sends a verification request to the webhook's callbackUrl once
every 100 callbacks. The subscriber should respond to the verification request
as described above -- failure to do so results in the webhook being disabled (enabled:
false and status: "DISABLED_VERIFICATION_FAILED").
# Webhook Status
A [Webhook](#section/Webhook-Object) object's **enabled** attribute indicates
whether a webhook is enabled or disabled, while the **status** attribute describes
the *reason* that the webhook is enabled or disabled.
The following table lists all possible combinations of **enabled** and **status**
attribute values.
Webhook.enabled | Webhook.status | Meaning | Notes
----- | ----- | ------ | -----
false | **DISABLED_ADMINISTRATIVE** | Webhook has been disabled by Smartsheet
support. | A webhook in this state can only be re-enabled by Smartsheet (contact
api@smartsheet.com). Attempting to re-enable
a webhook in this state results in error code 1154.
false | **DISABLED_APP_REVOKED** | Webhook has been disabled because the third-party
app associated with the webhook has had its access revoked. | This is a terminal
state (that is, webhook in this state cannot be re-enabled, and attempts to do
so result in error code 1153). If the third-party app's access is subsequently
restored, it must create new webhooks.
false | **DISABLED_BY_OWNER** | Webhook has been disabled by the owner. | Owner
can re-enable the webhook by using the [Update Webhook](../../tag/webhooks#operation/updateWebhook)
operation to set **enabled** to **true**. Once the subscriber successfully acknowledges
the [verification request](#section/Creating-a-Webhook/Webhook-Verification),
the webhook is enabled.
false | **DISABLED_CALLBACK_FAILED** | Webhook has been disabled because callback
was not successfully delivered to the callback URL. | Owner can re-enable the
webhook by using the [Update Webhook](../../tag/webhooks#operation/updateWebhook)
operation to set **enabled** to **true**. Once the subscriber successfully acknowledges
the [verification request](#section/Creating-a-Webhook/Webhook-Verification),
the webhook is enabled.
false | **DISABLED_SCOPE_INACCESSIBLE** | Webhook has been disabled because its
owner lost access to the corresponding data in Smartsheet (either because the
object was deleted or sharing permissions were revoked). | Webhook is automatically
re-enabled if access to data is restored (for example, if deleted object is restored
or sharing permissions are restored).
false | **DISABLED_VERIFICATION_FAILED** | Webhook verification has failed. | Owner
can re-enable the webhook by using the [Update Webhook](../../tag/webhooks#operation/updateWebhook)
operation to set **enabled** to **true**. Once the subscriber successfully acknowledges
the [verification request](#section/Creating-a-Webhook/Webhook-Verification),
the webhook is enabled.
true | **ENABLED** | Webhook is active. |
false | **NEW_NOT_VERIFIED** | Webhook has been created but is not enabled because
it has not yet been verified. | Owner can re-enable the webhook by using the
[Update Webhook](../../tag/webhooks#operation/updateWebhook) operation to set
**enabled** to **true**. Once the subscriber successfully acknowledges the [verification
request](#section/Creating-a-Webhook/Webhook-Verification), the webhook is enabled.
**NOTES:**
* When a Webhook object's enabled attribute is set to true, Smartsheet
is monitoring for the specified events and sends a [callback](#section/Webhook-Callbacks/Event-Callbacks)
to the callbackUrl when the events occur.
* When a Webhook object's enabled attribute is set to false, Smartsheet
is not monitoring for the specified events and does not send a callback to the
callbackUrl when the events occur. Depending on the value of the status
attribute, it may be possible to (re-)enable the webhook. (See below for details).
# Webhook Callbacks
A callback is the notification that Smartsheet sends to a webhook's **callbackUrl**.
There are two types of callbacks:
* [Event callback](#section/Webhook-Callbacks/Event-Callbacks): Alerts the subscriber
when the specified events have occurred in Smartsheet. This is the most common
type of callback.
* [Status Change callback](#section/Webhook-Callbacks/Status-Change-Callbacks):
Alerts the subscriber that a webhook has been automatically disabled due to loss
of access or automatically re-enabled due to restoration of access.
A Subscriber has the ability to verify the integrity of a callback payload (that
is, ensure that the message was not tampered with en route) and authenticate the
identity of its sender (that is, ensure that the callback did indeed originate
from Smartsheet).
For more information, see [Authenticating Callbacks](#section/Webhook-Callbacks/Authenticating-Callbacks-(optional)).
**NOTES:**
* Smartsheet webhooks do not support callbacks to servers using self-signed certificates.
The callback server must be using a signed certificate from a certificate authority.
* The callbackURL cannot be a private IP address.
* The callbackURL must use one of the following ports: 443 (default for HTTPS),
8000, 8008, 8080, or 8443.
## Event Callbacks
Smartsheet sends an event callback to notify the subscriber when the specified
events occur in Smartsheet.
WARNING: Any events that occur while a webhook is disabled are not communicated
via callback if/when webhook is enabled.
## Callback Acknowledgement
The subscriber must respond to an event callback with a 200 [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_Success)
to acknowledge that the callback was received.
## Retry Logic
If the subscriber fails to respond with a 200 status, depending on the response,
Smartsheet may retry delivery up to 14 times. (The first 7 retry attempts occur
with a frequency that's determined using exponential backoff; thereafter, retry
attempts occur once every three hours until all retries have been exhausted.)
Subscriber response | Is retried?
----- | -----
HTTP 201 through 299 | No
HTTP 309 through 399 | No
HTTP 400 through 499 (except 410) | Yes
HTTP 410 | No
HTTP 500 through 599 | Yes
Any other HTTP status | No
Request timeout | Yes
If the response is not retriable or retry attempts have been exhausted, the webhook
is disabled (**enabled: false** and **status: "DISABLED_CALLBACK_FAILED"**).
A webhook in this state can be re-enabled if the subscriber completes the verification
process. (See [Webhook Status](#section/Webhook-Status) for details.)
## Status Change Callbacks
If a webhook's owner loses access to the object that a webhook is monitoring (either
because the object was deleted or the webhook owner's access to the object was
revoked in Smartsheet),
Smartsheet automatically disables the webhook and sends a status change callback
to alert the subscriber of this change in status.
The **newWebhookStatus** attribute indicates that the webhook is now disabled
(because the scope is inaccessible).
If the webhook owner's access to the object is subsequently restored,
Smartsheet automatically re-enables the webhook and sends a status change callback
to alert the subscriber of this change in status.
The **newWebhookStatus** attribute indicates that the webhook is now enabled.
## Authenticating Callbacks (optional)
A subscriber has the ability to verify the integrity of a callback payload (that
is, ensure that the message was not tampered with en route) and authenticate the
identity of its sender (that is, ensure that the callback did indeed originate
from Smartsheet).
When you create a new [webhook](#section/Webhook-Object), it is assigned a randomly
generated **sharedSecret** value. The shared secret is used by Smartsheet to
sign callback payloads, and should not be shared with any third parties.
To authenticate a callback request:
1. Calculate the [HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)
of the webhook's **sharedSecret** and the request body. This must be done using
the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) cryptographic hash algorithm.
2. Format the calculated value as a string in base 16.
3. Compare your result with the value of the **Smartsheet-Hmac-SHA256** header
of the request.
If the values match, you can be sure the request originated from Smartsheet and
that the data has not been tampered with.
NOTE: For maximum security, you may also choose to [reset your webhook's shared
secret](../../tag/webhooks#operation/resetSharedSecret) at periodic intervals.
# Preventing Infinite Loops
It's possible that an application which subscribes to callbacks (using webhooks)
might react to those callbacks by using the API to make additional changes in
Smartsheet.
But, consider the following scenario:
1. **App1** creates a webhook to monitor **Sheet-A** for changes, specifying an
**App-1** URL as the **callbackUrl** for the webhook.
2. **App-1** updates **Sheet-A** using the API.
3. Smartsheet detects that **Sheet-A** has changed and sends a callback to **App-1**
(as the webhook specified).
4. **App-1** processes the callback, and in the course of doing so, updates **Sheet-A**
again using the API.
5. Return to Step 3.
To protect against infinite loops like the one outlined above, Smartsheet introduced
support for a new header that an API client can include with any API request that
adds, updates, or deletes data in Smartsheet.
Here's how it works:
* An API client includes the **Smartsheet-Change-Agent** header in any API request
that adds, updates, or deletes data in Smartsheet.
* The header value should be set to a string that the API client recognizes
as identifying itself.
* If any [event callbacks](../../tag/webhooksObjects#section/CallbackEvent-Object)
fire as a result of an API request that contains the **Smartsheet-Change-Agent**
header, the value of the **Smartsheet-Change-Agent** header is included in the
[callback](../../tag/webhooksObjects#section/Callback-Object) in the value of
the **changeAgent** attribute.
* If a webhook subscriber receives a [callback](../../tag/webhooksObjects#section/Callback-Object)
that contains the **changeAgent** attribute, it should evaluate the attribute
value:
* If the attribute value's comma-delimited list contains the subscriber API
client's change agent value, this indicates that the change which triggered the
callback *was* caused by the subscriber itself, and the subscriber can choose
to ignore the callback, thus preventing an infinite loop.
* Else, the change which triggered the callback was *not* caused by the subscriber
itself, and if the subscriber is going to subsequently react to the callback by
making a change in Smartsheet (via API request), the API client should append
a comma and its own identifier to the original attribute value, and pass that
value through using the **Smartsheet-Change-Agent** header of the API request.
Doing so protects against cross-system infinite loops.
NOTE: The Smartsheet-Change-Agent header value has a maximum length of
512 characters. If its length exceeds 512 characters, the excess is trimmed from
the front of the string, so that the most recent agent information remains.
# Webhook Errors
The following table specifies the recommended action for each Smartsheet-specific
error code.
Use this information to implement error handling logic according to the following
guidelines:
* If the error code indicates a permanent error condition, do not retry the request.
* If the error code indicates a problem that can be fixed, do not retry the request
until the problem has been fixed.
* If the error code indicates a problem that could be overcome by retrying the
request after a period of time, retry the request using exponential backoff.
HTTP status code | Smartsheet errorCode | Smartsheet message | Recommended Action
|
-----|-----|-----|-----|
400 | 1151 | Scope '{0}', object id {1} was not found. | Do not retry without
fixing the problem.
400 | 1152 | Only URLs with a protocol of 'https' are supported for attribute
'{0}'. | Do not retry without fixing the problem.
403 | 1153 | This webhook cannot be enabled because access was revoked for the
application that created it. | Do not retry.
403 | 1154 | Please contact api@smartsheet.com in order to enable this webhook.
| Do not retry.
- name: webhooksObjects
x-displayName: Objects
description: |
# Webhook Object
# Callback Object
# CallbackEvent Object
# SharedSecret Object
- name: workspaces
x-displayName: Methods
- name: workspacesDescription
x-displayName: Workspaces Basics
description: >
Similar to a folder, a workspace is a place where you can store
dashboards, reports, sheets, and templates to keep them organized. A
workspace offers more functionality than a folder because you can set up
sharing permissions and branding (a logo and a color scheme) at the
workspace-level and a workspace can contain folders so that you can keep
things within it organized. As new items are added to the workspace,
they’ll automatically inherit the sharing permissions and branding applied
to that workspace.
- name: workspacesObjects
x-displayName: Objects
description: |
# Workspace Object
- name: workspacesRelated
x-displayName: Related Items
description: >
# Workspace Folders
For details about working with folders in a workspace, see [Folders](../../tag/foldersDescription).
# Workspace Sheets
For details about working with sheets in a workspace, see [Sheets](../../tag/sheetsDescription).
x-tagGroups:
- name: Alternate Emails
tags:
- alternateEmailAddressDescription
- alternateEmailAddressObjects
- alternateEmailAddress
- name: Attachments
tags:
- attachmentsDescription
- attachmentsObjects
- attachments
- name: Automation Rules
tags:
- automationRulesDescription
- automationRulesObjects
- automationRules
- automationRulesRelated
- name: Cells
tags:
- cellsDescription
- cellsObjects
- cells
- cellsRelated
- name: Cell Images
tags:
- cellImagesDescription
- cellImagesObjects
- cellImages
- name: Columns
tags:
- columnsDescription
- columnsObjects
- columns
- columnsRelated
- name: Comments
tags:
- commentsDescription
- commentsObjects
- comments
- commentsRelated
- name: Common Objects
tags:
- commonObjects
- name: Contacts
tags:
- contactsDescription
- contactsObjects
- contacts
- name: Cross-sheet References
tags:
- crossSheetReferencesDescription
- crossSheetReferencesObjects
- crossSheetReferences
- name: Dashboards
tags:
- dashboardsDescription
- dashboardsObjects
- dashboards
- name: Discussions
tags:
- discussionsDescription
- discussionsObjects
- discussions
- discussionsRelated
- name: Events
tags:
- eventsDescription
- eventsObjects
- events
- name: Favorites
tags:
- favoritesDescription
- favoritesObjects
- favorites
- name: Folders
tags:
- foldersDescription
- foldersObjects
- folders
- name: Groups
tags:
- groupsDescription
- groupsObjects
- groups
- name: Group Members
tags:
- groupMembersDescription
- groupMembersObjects
- groupMembers
- name: Home
tags:
- homeDescription
- homeObjects
- home
- homeRelated
- name: Import
tags:
- importDescription
- import
- name: Proofs
tags:
- proofsDescription
- proofsObjects
- proofs
- name: Reports
tags:
- reportsDescription
- reportsObjects
- reports
- reportsRelated
- name: Rows
tags:
- rowsDescription
- rowsObjects
- rows
- rowsRelated
- name: Search
tags:
- searchDescription
- searchObjects
- search
- name: Send Via Email
tags:
- sendViaEmailDescription
- sendViaEmailObjects
- sendViaEmail
- name: Server Information
tags:
- serverInfoDescription
- serverInfoObjects
- serverInfo
- name: Sharing
tags:
- sharingDescription
- sharingObjects
- sharing
- name: Sheet Summary
tags:
- sheetSummaryDescription
- sheetSummaryObjects
- sheetSummary
- name: Sheets
tags:
- sheetsDescription
- sheetsObjects
- sheets
- sheetsRelated
- name: Templates
tags:
- templatesDescription
- templatesObjects
- templates
- name: Token
tags:
- tokenDescription
- tokenObjects
- token
- name: Update Requests
tags:
- updateRequestsDescription
- updateRequestsObjects
- updateRequests
- name: Users
tags:
- usersDescription
- usersObjects
- users
- name: Webhooks
tags:
- webhooksDescription
- webhooksObjects
- webhooks
- name: Workspaces
tags:
- workspacesDescription
- workspacesObjects
- workspaces
- workspacesRelated
paths:
/contacts:
parameters:
- name: Authorization
in: header
description: |
API Access Token used to authenticate requests to Smartsheet APIs.
schema:
type: string
example: Bearer ll352u9jujauoqz4gstvsae05
get:
operationId: list-contacts
summary: List Contacts
description: Gets a list of the user's Smartsheet contacts.
tags:
- contacts
security:
- APIToken: []
- OAuth2:
- READ_CONTACTS
parameters:
- name: includeAll
in: query
required: false
description: If true, include all results, that is, do not paginate. Mutually
exclusive with page and pageSize (they are ignored if includeAll=true is
specified).
schema:
type: boolean
default: false
- name: modifiedSince
in: query
required: false
description: When specified with a date and time value, response only includes
the objects that are modified on or after the date and time specified. If
you need to keep track of frequent changes, it may be more useful to use
Get Sheet Version.
schema:
$ref: '#/components/schemas/Attachment/properties/createdAt'
- name: numericDates
in: query
schema:
type: boolean
default: false
description: 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.
- name: page
in: query
required: false
description: 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.
schema:
type: number
default: 1
- name: pageSize
in: query
required: false
description: 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.
schema:
type: number
default: 100
responses:
'200':
description: IndexResult object containing an array of Contact objects
content:
application/json:
schema:
allOf:
- type: object
properties:
pageNumber:
description: 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.
type: number
example: 1
readOnly: true
pageSize:
description: 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.
type: number
example: 50
nullable: true
readOnly: true
totalPages:
description: The total number of pages in the full result set.
type: number
example: 25
readOnly: true
totalCount:
description: The total number of items in the full result set.
type: number
example: 136
readOnly: true
- type: object
properties:
data:
description: List of Contacts
type: array
items:
type: object
properties:
id:
description: Contact Id.
type: string
example: AAAAATYU54QAD7_fNhTnhA
name:
description: Contact's full name.
type: string
example: Jane Doe
email:
description: Contact's email address.
type: string
format: email
example: jane.doe@smartsheet.com
'401':
description: |
Unauthorized. See Smartsheet Error Code and Message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
examples:
1001Example:
summary: 401 - 1001 - An Access Token is required
value:
errorCode: 1001
message: An Access Token is required
refId: exlxshtxlpl8
1002Example:
summary: 401 - 1002 - Your Access Token is invalid
value:
errorCode: 1003
message: Your Access Token is invalid
refId: exlxshtxlpl8
1003Example:
summary: 401 - 1003 - Your Access Token has expired
value:
errorCode: 1003
message: Your Access Token has expired
refId: exlxshtxlpl8
1005Example:
summary: 401 - 1005 - Single Sign-On is required for this account
value:
errorCode: 1005
message: Single Sign-On is required for this account
refId: exlxshtxlpl8
1030Example:
summary: 401 - 1030 - You are unable to assume the user specified
value:
errorCode: 1030
message: You are unable to assume the user specified
refId: exlxshtxlpl8
1067Example:
summary: 401 - 1067 - Invalid client_id
value:
errorCode: 1067
message: Invalid client_id
refId: exlxshtxlpl8
'404':
description: |
Not Found. See Smartsheet Error Code and Message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
examples:
1006Example:
summary: 404 - 1006 - Not Found
value:
errorCode: 1006
message: Not Found
refId: exlxshtxlpl8
'500':
description: >
Internal Server Error. See Smartsheet Error Code and Message for
details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
examples:
1119Example:
summary: 500 - 1119 - Failed to complete copy
value:
errorCode: 1119
message: Failed to complete copy.
refId: exlxshtxlpl8
1170Example:
summary: 500 - 1170 - The sheet referenced by this widget is unavailable
or deleted.
value:
errorCode: 1170
message: The sheet referenced by this widget is unavailable or
deleted.
refId: exlxshtxlpl8
1171Example:
summary: 500 - 1171 - The report referenced by this widget is unavailable
or deleted.
value:
errorCode: 1171
message: The report referenced by this widget is unavailable or
deleted.
refId: exlxshtxlpl8
1172Example:
summary: 500 - 1172 - The referenced cell is unavailable or deleted.
value:
errorCode: 1172
message: The referenced cell is unavailable or deleted.
refId: exlxshtxlpl8
1278Example:
summary: 500 - 1278 - Proofing service error.
value:
errorCode: 1278
message: Proofing service error.
refId: exlxshtxlpl8
1285Example:
summary: 500 - 1285 - Dashboard source profile field missing.
value:
errorCode: 1285
message: Dashboard source profile field missing.
refId: exlxshtxlpl8
4000Example:
summary: 500 - 4000 - An unexpected error has occurred. Please contact
api@smartsheet.com for assistance.
value:
errorCode: 4000
message: An unexpected error has occurred. Please contact api@smartsheet.com
for assistance.
refId: exlxshtxlpl8
4001Example:
summary: 500 - 4001 - Smartsheet.com is currently offline for system
maintenance. Please check back again shortly.
value:
errorCode: 4001
message: Smartsheet.com is currently offline for system maintenance.
Please check back again shortly.
refId: exlxshtxlpl8
4002Example:
summary: 500 - 4002 - Server timeout exceeded. Request has failed.
value:
errorCode: 4002
message: Server timeout exceeded. Request has failed.
refId: exlxshtxlpl8
4004Example:
summary: 500 - 4004 - An unexpected error has occurred. Please retry
your request. If you encounter this error repeatedly, please contact
api@smartsheet.com for assistance.
value:
errorCode: 4004
message: An unexpected error has occurred. Please retry your request.
If you encounter this error repeatedly, please contact api@smartsheet.com
for assistance.
refId: exlxshtxlpl8
4004Example2:
summary: 500 - 4004 - 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.
value:
errorCode: 4004
message: 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.
refId: exlxshtxlpl8
5151Example:
summary: 500 - 5151 - The action could not be completed because
the following people are outside of the approved domain sharing
list:[email address]
value:
errorCode: 5151
message: The action could not be completed because the following
people are outside of the approved domain sharing list:[email
address]
refId: exlxshtxlpl8
5502Example:
summary: 500 - 5502 - You must have sheet admin permission to save
a notification with recipients other than yourself.
value:
errorCode: 5502
message: You must have sheet admin permission to save a notification
with recipients other than yourself.
refId: exlxshtxlpl8
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/contacts \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult contacts\
\ = smartsheet.ContactResources.ListContacts(\n null //\
\ PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult contacts = smartsheet.contactResources().listContacts(\n\
\ null // PaginationParameters\n );\n"
- lang: JavaScript
source: "smartsheet.contacts.listContacts({})\n .then(function(contactsList)\
\ {\n console.log(contactsList);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Contacts.list_contacts(include_all=True)\n\
contacts = response.data\n\n# Sample 2: Paginate the list (100 contacts\
\ per page)\nresponse = smartsheet_client.Contacts.list_contacts(\n page_size=100,\n\
\ page=1)\npages = response.total_pages\ncontacts = response.data\n"
- lang: Ruby
source: "response = smartsheet.contacts.list\ncontacts = response[:data]\n"
/contacts/{contactId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: contactId
in: path
schema:
type: number
required: true
description: contactId of the contact being accessed.
get:
summary: Get Contact
description: Gets the specified contact.
operationId: get-contact
tags:
- contacts
security:
- APIToken: []
- OAuth2:
- READ_CONTACTS
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of optional elements to include in the
response:
* **profileImage**
schema:
type: string
enum:
- profileImage
responses:
'200':
description: Returns Contact object
content:
application/json:
schema:
$ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/contacts/{contactId} \\\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Contact contact = smartsheet.ContactResources.GetContact(\n \"AAAAATYU54QAD7_fNhTnhA\"\
\ // string contactId\n);\n"
- lang: Java
source: "Contact contact = smartsheet.contactResources().getContact(\n \
\ \"AAAAATYU54QAD7_fNhTnhA\" // string contactId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {id: \"AAAAATYU54QAD7_fNhTnhA\"};\n\
\n// Get contact\nsmartsheet.contacts.getContact(options)\n .then(function(contact)\
\ {\n console.log(contact);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "contact = smartsheet_client.Contacts.get_contact(\n 'AAAAATYU54QAD7_fNhTnhA')\
\ # contact_id\n"
- lang: Ruby
source: "contact = smartsheet.contacts.get(\n contact_id: 'AAAAATYU54QAD7_fNhTnhA'\n\
)\n"
/events:
get:
operationId: list-events
summary: List Events
description: >-
Gets events that are occurring in your Smartsheet organization account.
Examples of events are creation, update, load, and delete of sheets,
reports, dashboards, attachments, users, etc.
Each event type has a distinct combination of objectType and action. Many
event types have additional information returned under an additionalDetails
object. See the Event Reporting reference documentation for a complete list
of all currently supported events, including their respective objectType,
action, and additionalDetails properties.
tags:
- events
security:
- APIToken: []
- OAuth2:
- READ_EVENTS
parameters:
- name: Accept-Encoding
in: header
description: >
Strongly recommended to make sure payload is compressed. Must be set
to one of the following values:
* deflate
* gzip
schema:
type: string
enum:
- deflate
- gzip
required: false
- $ref: '#/paths/~1contacts/parameters/0'
- name: since
in: query
description: >-
Starting time for events to return. Intended for use only at client
startup or recovery. This is intended for backfilling data and not
for fine-grained date-based queries. Therefore, resolution is
limited to the nearest hour. Interpreted as ISO-8601 format, unless
numericDates is specified (see details about numericDates below)
You must pass in a value for either since or streamPosition and never both.
schema:
type: string
format: date-time
required: false
- name: streamPosition
in: query
description: >-
Indicates next set of events to return. Use value of
nextStreamPosition returned from the previous call.
You must pass in a value for either since or streamPosition and never both.
schema:
type: string
example: XyzAb1234cdefghijklmnofpq
required: false
- name: maxCount
in: query
description: |-
Maximum number of events to return as response to this call.
Must be between 1 through 10,000 (inclusive).
Defaults to 1,000 if not specified.
schema:
type: integer
minimum: 1
maximum: 10000
default: 1000
required: false
- name: numericDates
in: query
description: >-
If true, dates are accepted and returned in Unix epoch time
(milliseconds since midnight on January 1, 1970 in UTC time).
Default is false, which means ISO-8601 format.
schema:
type: boolean
default: false
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- description: StreamResult Object
type: object
properties:
nextStreamPosition:
description: This string should be passed back to the next GET
events call to obtain subsequent events.
type: string
example: XyzAb1234cdefghijklmnofpq
moreAvailable:
description: True if more results are available. This is typically
due to event counts exceeding the maxCount parameter passed
in.
type: boolean
example: true
- type: object
properties:
data:
description: List of Events
type: array
items:
description: An Event object for event reporting.
type: object
properties:
eventId:
description: Unique event identifier.
type: string
example: 4b12345abc444def333g149he2b15b3j
objectType:
description: The Smartsheet resource impacted by the event,
such as, SHEET or WORKSPACE.
type: string
enum:
- SHEET
- WORKSPACE
example: sheet
action:
description: The action applied to the specified object,
such as CREATE or DELETE.
type: string
example: CREATE
objectId:
description: The identifier of the object impacted by
the event.
type: string
example: 345678901234
eventTimeStamp:
description: Date and time of the event. Defaults to ISO-8601
format. See dates and times for more information.
type: string
format: date-time
userId:
description: User assumed as the one who initiated the
event. Usually the userId property and the requestUserId
property (below) have the same value. However, if the
request is an API call with Assume-User header then
the userId property identifies the user whose email
matches the value in the Assume-User header.
type: number
example: 123457654321
requestUserId:
description: User whose authentication credential is embedded
in the request that initiated the event. For example,
if the request is an API call with an access token then
requestUserId identifies the user whose data can be
accessed via the access token (i.e., the user who authorized
the creation of the access token). On the other hand,
if the request comes from a UI session, then requestUserId
identifies the user logged-in to the UI.
type: number
example: 133445566778
accessTokeName:
description: Name of the access token embedded in the
request. This property is omitted if there is no access
token in the request (i.e., it isn't an API call) or
if the access token wasn't given a name when created
(only access tokens generated via the Smartsheet desktop
UI can be given a name at creation time).
type: number
nullable: true
source:
description: Identifies the type of action that triggered
the event.
type: string
example: WEB_APP
additionalDetails:
description: Container object for additional event-specific
properties. Properties depend upon the event type. See
[Event Reporting](https://smartsheet-platform.github.io/event-reporting-docs/)
reference documentation for details on each event type.
type: object
additionalProperties: true
'400':
description: Bad Request. See Smartsheet Error Code and Message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
'401':
$ref: '#/paths/~1contacts/get/responses/401'
'403':
description: |
Forbidden. See Smartsheet Error Code and Message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
'404':
$ref: '#/paths/~1contacts/get/responses/404'
'405':
description: >
Method Not Allowed. See Smartsheet Error Code and Message for
details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
examples:
1010Example:
summary: 404 - 1010 - HTTP Method Not Supported
value:
errorCode: 1010
message: HTTP Method Not Supported
refId: exlxshtxlpl8
1122Example:
summary: '404 - 1122 - Requested URL does not support this method:
{0}'
value:
errorCode: 1122
message: 'Requested URL does not support this method: {0}.'
refId: exlxshtxlpl8
'406':
description: |
Not Acceptable. See Smartsheet Error Code and Message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
examples:
1052Example:
summary: Invalid Accept header. Media type not supported.
value:
errorCode: 1052
message: Invalid Accept header. Media type not supported.
refId: exlxshtxlpl8
'410':
description: |
Gone. See Smartsheet Error Code and Message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
examples:
4005Example:
summary: API Version Retired.
value:
errorCode: 4005
message: API Version Retired.
refId: exlxshtxlpl8
'415':
description: |
Gone. See Smartsheet Error Code and Message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
examples:
1124Example:
summary: Invalid Content-Type header. Media type not supported.
value:
errorCode: 1124
message: Invalid Content-Type header. Media type not supported.
refId: exlxshtxlpl8
'429':
description: |
Gone. See Smartsheet Error Code and Message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
examples:
4003Example:
summary: Rate limit exceeded.
value:
errorCode: 4003
message: Rate limit exceeded.
refId: exlxshtxlpl8
'500':
$ref: '#/paths/~1contacts/get/responses/500'
/favorites:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Favorites
description: Gets a list of all of the user's favorite items.
operationId: get-favorites
tags:
- favorites
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: IndexResult object containing an array of Favorite objects.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
type: array
items:
type: object
properties:
objectId:
description: The Id of the favorited item. If type is
template, only private sheet-type template Id is allowed.
type: number
type:
type: string
enum:
- folder
- report
- sheet
- sight
- template
- workspace
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/favorites \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult results\
\ = smartsheet.FavoriteResources.ListFavorites(\n null //\
\ PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult results = smartsheet.favoriteResources().listFavorites(\n\
\ null // PaginationParameters\n );\n"
- lang: JavaScript
source: "smartsheet.favorites.listFavorites()\n .then(function(favoritesList)\
\ {\n console.log(favoritesList);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Favorites.list_favorites(include_all=True)\n\
faves = response.data\n"
- lang: Ruby
source: "response = smartsheet.favorites.list\nlist = response[:data]\n"
post:
summary: Add Favorites
description: >
Adds one or more items to the user's list of favorite items. This
operation supports both single-object and bulk semantics. For more
information, see Optional Bulk Operations.
If called with a single Favorite object, and that favorite already exists,
error code 1129 is returned. If called with an array of Favorite objects,
any objects specified in the array that are already marked as favorites are
ignored and omitted from the response.
operationId: add-favorite
tags:
- favorites
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
parameters:
- name: Content-Type
in: header
description: >
Required for POST and PUT requests. Defines the structure for the
request body.
schema:
type: string
default: application/json
requestBody:
description: A list of favorites to be added.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1favorites/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
- type: array
items:
$ref: '#/paths/~1favorites/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
responses:
'200':
description: Result object containing either a single Favorite object or
an array of Favorite objects.
content:
application/json:
schema:
allOf:
- type: object
allOf:
- type: object
allOf:
- type: object
properties:
message:
description: Message that indicates the outcome of the request.
(One of SUCCESS or PARTIAL_SUCCESS.)
type: string
enum:
- PARTIAL_SUCCESS
- SUCCESS
example: SUCCESS
resultCode:
description: |-
* '0' Success
* '3' Partial Success of Bulk Operation
type: number
enum:
- 0
- 3
properties:
failedItems:
description: Array of BulkItemFailure objects which represents
the items that failed to be added or updated. See [Partial
Success](/partial-success) for more information. Applicable
only for bulk operations that support partial success.
type: array
items:
$ref: '#/components/schemas/Result/allOf/0/properties/failedItems/items'
nullable: true
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1favorites/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
- type: array
items:
$ref: '#/paths/~1favorites/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: Generic Error Payload.
content:
application/json:
schema:
$ref: '#/paths/~1favorites/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/favorites \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X POST \\\n-d '[{\"type\": \"sheet\", \"objectId\": 8400677765441412}]'\n"
- lang: C#
source: "// Specify favorites\nIList favoritesSpecification = new\
\ Favorite[]\n{\n new Favorite\n {\n Type = ObjectType.SHEET,\n \
\ ObjectId = 8400677765441412\n }\n};\n\n// Add items to favorites\nIList\
\ newFavorite = smartsheet.FavoriteResources.AddFavorites(favoritesSpecification);\n"
- lang: Java
source: "// Specify favorites\nFavorite favoritesSpecification = new Favorite()\n\
\ .setObjectId(8400677765441412L)\n .setType(FavoriteType.SHEET);\n\
\n// Add items to favorites\nList newFavorite = smartsheet.favoriteResources().addFavorites(Arrays.asList(favoritesSpecification));\n"
- lang: JavaScript
source: "// Specify favorites\nvar favorites = [\n {\n \"type\": \"sheet\"\
,\n \"objectId\": 8400677765441412\n }\n];\n\n// Set options\nvar options\
\ = {\n body: favorites\n};\n\n// Add items to favorites\nsmartsheet.favorites.addItemsToFavorites(options)\n\
\ .then(function(newFavorite) {\n console.log(newFavorite);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Favorites.add_favorites([\n smartsheet.models.Favorite({\n\
\ 'type': 'sheet',\n 'object_id': 8400677765441412\n })\n])\n"
- lang: Ruby
source: "# Specify favorites\nbody = {\n type: 'sheet',\n object_id: 8400677765441412\n\
}\n\n# Add items to favorites\nresponse = smartsheet.favorites.add(\n body:\
\ body\n)\n"
/favorites/{favoriteType}:
parameters:
- name: favoriteType
in: path
schema:
type: string
enum:
- folder
- report
- sheet
- sight
- template
- workspace
required: true
description: The favorite type.
- $ref: '#/paths/~1contacts/parameters/0'
delete:
summary: Remove Multiple Favorites
description: Removes all favorites with the same type for the user.
operationId: delete-favorites-by-type
tags:
- favorites
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
responses:
'200':
description: Returns Result object.
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
default:
description: Generic Error Payload.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/favorites/{favoriteType}?objectIds=favoriteId1,favoriteId2'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.FavoriteResources.RemoveFavorites(\n ObjectType.FOLDER,\n\
\ new long[] { 2252168947361668, 2252168947361669 } // folderIds\n\
);\n"
- lang: Java
source: "smartsheet.favoriteResources().removeFavorites(\n FavoriteType.FOLDER,\n\
\ new HashSet(Arrays.asList(2252168947361668L, 2252168947361669L))\
\ // long folderIds\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n queryParameters: {\n objectIds:\
\ \"2252168947361668,2252168947361669\"\n }\n};\n\n// Remove favoriteType\
\ from list of favorites\nsmartsheet.favorites.remove{favoriteType}FromFavorites(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Favorites.remove_favorites(\n 'folder',\n [2252168947361668,\
\ 2252168947361669] # folder_ids\n)\n"
- lang: Ruby
source: "smartsheet.favorites.remove_folders(\n folder_ids: [2252168947361668,\
\ 2252168947361669]\n)\n"
/favorites/{favoriteType}/{favoriteId}:
parameters:
- $ref: '#/paths/~1favorites~1%7BfavoriteType%7D/parameters/0'
- name: favoriteId
in: path
schema:
type: number
required: true
description: Favorite Id, e.g., sheet Id, report Id.
- $ref: '#/paths/~1contacts/parameters/0'
delete:
summary: Remove Favorite
description: Removes a single favorite from the user's list of favorite items
by type and ID.
operationId: delete-favorites-by-type-and-id
tags:
- favorites
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
responses:
'200':
description: Returns Result object.
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/favorites/{favoriteType}/{folderId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.FavoriteResources.RemoveFavorites(\n ObjectType.FOLDER,\n\
\ new long[] { 2252168947361668 } // folderId\n);\n"
- lang: Java
source: "smartsheet.favoriteResources().removeFavorites(\n FavoriteType.FOLDER,\n\
\ new HashSet(Arrays.asList(2252168947361668L)) // long folderId\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n objectId: 2252168947361668\n};\n\
\n// Remove folder from list of favorites\nsmartsheet.favorites.removeFolderFromFavorites(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Favorites.remove_favorites(\n 'folder',\n 2252168947361668\
\ # folder_id\n)\n"
- lang: Ruby
source: "smartsheet.favorites.remove_folder(\n folder_id: 2252168947361668\n\
)\n"
/folders/{folderId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: folderId
in: path
schema:
type: number
required: true
description: Folder Id where you can create sheets, sights, reports, templates,
and other folders.
get:
summary: Get Folder
description: Gets a Folder object.
tags:
- folders
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: get-folder
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of optional elements to include in the
response:
* **source** - adds the Source object indicating which object the folder
was created from, if any
* **distributionLink**
* **ownerInfo**
* **sheetVersion**
* **permalinks**
schema:
type: string
enum:
- source
- distributionLink
- ownerInfo
- sheetVersion
- permalinks
responses:
'200':
description: A single Folder object.
content:
application/json:
schema:
$ref: '#/components/schemas/Folder/properties/folders/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/folders/{folderId} \\\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Sample 1: Omit 'include' parameter\nFolder folder = smartsheet.FolderResources.GetFolder(\n\
\ 7116448184199044, // long folderId\n null \
\ // IEnumerable include\n);\n\n// Sample 2: Specify\
\ 'include' parameter with value of \"SOURCE\"\nFolder folder = smartsheet.FolderResources.GetFolder(\n\
\ 7116448184199044, // long folderId\n new FolderInclusion[]\
\ {\n FolderInclusion.SOURCE }\n);\n"
- lang: Java
source: "// Sample 1: Omit 'include' parameter\nFolder folder = smartsheet.folderResources().getFolder(\n\
\ 7116448184199044L, // long folderId\n null) \
\ // EnumSet includes\n );\n\n// Sample\
\ 2: Specify 'include' parameter with value of \"SOURCE\"\nFolder folder\
\ = smartsheet.folderResources().getFolder(\n 7116448184199044L,\
\ // long folderId\n EnumSet.of(SourceInclusion.SOURCE))\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n id: 7116448184199044 // Id of\
\ Folder\n};\n\n// Get folder\nsmartsheet.folders.getFolder(options)\n \
\ .then(function(folder) {\n console.log(folder);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "folder = smartsheet_client.Folders.get_folder(\n 7116448184199044)\
\ # folder_id\n"
- lang: Ruby
source: "folder = smartsheet.folders.get(\n folder_id: 7116448184199044\n\
)\n"
delete:
summary: Delete Folder
description: Deletes a folder.
tags:
- folders
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
operationId: delete-folder
responses:
'200':
description: |
Returns Result object
content:
application/json:
schema:
type: object
properties:
message:
description: Message that indicates the outcome of the request.
(One of SUCCESS or PARTIAL_SUCCESS.)
type: string
enum:
- PARTIAL_SUCCESS
- SUCCESS
example: SUCCESS
resultCode:
description: |-
* '0' Success
* '3' Partial Success of Bulk Operation
type: number
enum:
- 0
- 3
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/folders/{folderId} \\\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.FolderResources.DeleteFolder(\n 965780272637828 \
\ // long folderId\n);\n"
- lang: Java
source: "smartsheet.folderResources().deleteFolder(\n 965780272637828L\
\ // long folderId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n id: 965780272637828 // Id of Folder\n\
};\n\n// Delete folder\nsmartsheet.folders.deleteFolder(options)\n .then(function(results)\
\ {\n console.log(results);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Folders.delete_folder(\n 7960873114331012) \
\ # folder_id\n"
- lang: Ruby
source: "smartsheet.folders.delete(\n folder_id: 2252168947361668\n)\n"
put:
summary: Update Folder
description: Updates a folder.
operationId: update-folder
tags:
- folders
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/get/responses/200/content/application~1json/schema'
responses:
'200':
description: Result object containing the modified Folder object.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1folders~1%7BfolderId%7D/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/folders/{folderId} \\\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{\"name\": \"New name for folder\"\
}'\n"
- lang: C#
source: "// Set folder name\nFolder folderSpecification = new Folder\n{\n\
\ Id = 7960873114331012,\n Name = \"New name for folder\"\n};\n\n// Update\
\ folder\nFolder updatedFolder = smartsheet.FolderResources.UpdateFolder(folderSpecification);\n"
- lang: Java
source: "// Set folder name and id of the folder to be updated\nFolder folderSpecification\
\ = new Folder(7960873114331012L);\nfolderSpecification.setName(\"New name\
\ for folder\");\n\n// Update folder\nFolder updatedFolder = smartsheet.folderResources().updateFolder(folderSpecification);\n"
- lang: JavaScript
source: "// Set folder name\nvar folder = {\n \"name\": \"New name for folder\"\
\n};\n\n// Set options\nvar options = {\n id: 7960873114331012, // Id of\
\ Folder\n body: folder\n};\n\n// Update folder\nsmartsheet.folders.updateFolder(options)\n\
\ .then(function(updatedFolder) {\n console.log(updatedFolder);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_folder = smartsheet_client.Folders.update_folder(\n 7960873114331012,\
\ # folder_id\n 'New name for folder')\n"
- lang: Ruby
source: "# Set options\nbody = {\n name: 'New name for folder'\n}\n\n# Update\
\ folder\nresponse = smartsheet.folders.update(\n folder_id: 7960873114331012,\n\
\ body: body\n)\n"
/folders/{folderId}/copy:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D/parameters/1'
post:
summary: Copy Folder
description: Copies a folder.
tags:
- folders
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
operationId: copy-folder
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- name: include
in: query
required: false
description: >
A comma-separated list of elements to copy:
* **attachments**
* **cellLinks** - includes cross-sheet references
* **data** - includes formatting
* **discussions** - includes comments
* **filters**
* **forms**
* **ruleRecipients** -- includes notification recipients, must also include
rules when using this attribute
* **rules** -- includes notifications and workflow rules
* **shares** |
NOTE: Cell history is not copied, regardless of which include parameter
values are specified.
schema:
type: string
enum:
- attachments
- cellLinks
- data
- discussions
- filters
- forms
- ruleRecipients
- rules
- shares
- name: exclude
in: query
required: false
description: When specified with a value of **sheetHyperlinks**, excludes
this category from the response
schema:
type: string
enum:
- sheetHyperlinks
- name: skipRemap
in: query
description: A comma-separated list of references to NOT re-map for the newly
created folder.
schema:
type: string
enum:
- cellLinks
- reports
- sheetHyperlinks
- sights
required: false
requestBody:
description: New folder name.
required: true
content:
application/json:
schema:
oneOf:
- type: object
properties:
destinationId:
description: The Id of the destination container (when copying
or moving a sheet or a folder). Required if destinationType
is "folder" or "workspace". If destinationType is "home", this
value must be null.
type: number
destinationType:
description: Type of the destination container.
type: string
nullable: true
enum:
- folder
- home
- workspace
newName:
description: Name of the newly created object (when creating a
copy of a dashboard, folder, sheet, or workspace). This attribute
is not supported for "move" operations.
type: string
responses:
'200':
description: Result object containing a Folder object for the new folder
destination.
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/folders/{folderId}/copy?include=data'\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n-H \"Content-Type:\
\ application/json\"\n-d '{\n \"destinationType\": \"folder\",\n \"destinationId\"\
: 7960873114331012,\n \"newName\": \"newFolderName\"\n}'\n-X POST\n"
- lang: C#
source: "// Specify destination\nContainerDestination destination = new ContainerDestination\
\ {\n DestinationId = 7960873114331012,\n DestinationType = DestinationType.FOLDER,\n\
\ NewName = \"newFolderName\"\n};\n\n// Sample 1: Omit 'include' and 'skipRemap'\
\ parameters\nFolder folder = smartsheet.FolderResources.CopyFolder(\n \
\ 2252168947361668, // long folderId\n destination,\n null,\
\ // IEnumerable include\n\
\ null // IEnumerable\
\ skipRemap\n);\n\n// Sample 2: Specify 'include' parameter with value of\
\ \"DATA\", and 'skipRemap' parameter with value of \"CELL_LINKS\"\nFolder\
\ folder = smartsheet.FolderResources.CopyFolder(\n 2252168947361668, \
\ // long folderId\n destination,\n new FolderCopyInclusion[]\
\ {\n FolderCopyInclusion.DATA },\n new FolderRemapExclusion[] {\n \
\ FolderRemapExclusion.CELL_LINKS }\n);\n"
- lang: Java
source: "// Specify destination\nContainerDestination destination = new ContainerDestination()\n\
\ .setDestinationType(DestinationType.FOLDER)\n .setDestinationId(7960873114331012L)\n\
\ .setNewName(\"newFolderName\");\n\n// Sample 1: Omit 'include'\
\ and 'skipRemap' parameters\nFolder folder = smartsheet.folderResources().copyFolder(\n\
\ 2252168947361668L, // long folderId\n \
\ destination,\n null, // EnumSet\
\ includes\n null // EnumSet\
\ skipRemap\n );\n\n// Sample 2: Specify 'include' parameter with\
\ value of \"DATA\", and 'skipRemap' parameter with value of \"CELLLINKS\"\
\nFolder folder = smartsheet.folderResources().copyFolder(\n 2252168947361668L,\
\ // long folderId\n destination,\n EnumSet.of(FolderCopyInclusion.DATA),\n\
\ EnumSet.of(FolderRemapExclusion.CELLLINKS)\n );\n"
- lang: JavaScript
source: "// Specify destination information\nvar body = {\n destinationType:\
\ \"folder\",\n destinationId: 7960873114331012,\n newName: \"Folder Copy\"\
\n};\n\n// Specify elements to copy\nvar params = {\n include: \"data,discussions\"\
,\n skipRemap: \"cellLinks\"\n};\n\n// Set options\nvar options = {\n \
\ folderId: 2252168947361668,\n body: body,\n queryParameters: params\n\
};\n\n// Copy folder\nsmartsheet.folders.copyFolder(options)\n .then(function(folder)\
\ {\n console.log(folder);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Folders.copy_folder(\n 2252168947361668,\
\ # folder_id\n smartsheet.models.ContainerDestination({\n\
\ 'destination_id': 7960873114331012,\n 'destination_type': 'folder',\n\
\ 'new_name': 'newFolderName'\n })\n)\n"
- lang: Ruby
source: "# Specify destination information\nbody = {\n destination_type:\
\ 'folder',\n destination_id: 7960873114331012,\n new_name: 'newFolderName'\n\
}\n\n# Copy folder\nresponse = smartsheet.folders.copy(\n folder_id: 2252168947361668,\n\
\ body: body\n)\n"
/folders/{folderId}/folders:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D/parameters/1'
get:
summary: List Folders
description: >
Gets a list of folders in a given folder. The list contains an
abbreviated Folder object for each folder.
tags:
- folders
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: list-folders
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: IndexResult object containing an array of Folder objects.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Folder/properties/folders/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/folders/{folderId}/folders \\\
\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult folders =\
\ smartsheet.FolderResources.ListFolders(\n 5107651446105988, \
\ // long folderId\n null // PaginationParameters\n\
);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult folders = smartsheet.folderResources().listFolders(\n\
\ 510765144610598L, // long parentFolderId\n \
\ null // PaginationParameters\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n folderId: 5107651446105988\n};\n\
\n// List folders in another folder\nsmartsheet.folders.listChildFolders(options)\n\
\ .then(function(folderList) {\n console.log(folderList);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Folders.list_folders(\n\
\ 5107651446105988, # folder_id\n include_all=True)\nfolders = response.data\n\
\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Folders.list_folders(\n\
\ 5107651446105988, # folder_id\n page_size=5,\n page=1)\npages\
\ = response.total_pages\nfolders = response.data\n"
- lang: Ruby
source: "response = smartsheet.folders.list_in_folder(\n folder_id: 5107651446105988\n\
)\nfolders = response[:data]\n"
post:
summary: Create Folder
description: |
Creates a new folder.
operationId: create-folder-folder
tags:
- folders
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/parameters/1'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/parameters/2'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/parameters/3'
requestBody:
description: Folder to create.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1folders/get/responses/200/content/application~1json/schema/allOf/1/properties/result/items'
responses:
'200':
description: Result object containing a Folder object for newly created
folder.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1folders/get/responses/200/content/application~1json/schema/allOf/1/properties/result/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D~1folders/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/folders/{folderid}/folders \\\
\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"name\": \"New folder\"}'\n"
- lang: C#
source: "// Set folder name\nFolder folderSpecification = new Folder { Name\
\ = \"New folder\" };\n\n// Create folder in another folder\nFolder newFolder\
\ = smartsheet.FolderResources.CreateFolder(\n 7960873114331012, \
\ // long destinationFolderId\n folderSpecification\n);\n"
- lang: Java
source: "// Set folder name\nFolder folderSpecification = new Folder();\n\
folderSpecification.setName(\"New Folder\");\n\n// Create folder in another\
\ folder\nFolder newFolder = smartsheet.folderResources().createFolder(\n\
\ 7960873114331012L, // long destinationFolderId\n folderSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Set folder name\nvar folder = {\n \"name\": \"New folder\"\n\
};\n\n// Set options\nvar options = {\n folderId: 7960873114331012,\n \
\ body: folder\n };\n\n// Create folder in another folder\nsmartsheet.folders.createChildFolder(options)\n\
\ .then(function(newFolder) {\n console.log(newFolder);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Folders.create_folder_in_folder(\n \
\ 7960873114331012, # folder_id\n 'New folder')\n"
- lang: Ruby
source: "body = {\n name: 'New Folder'\n}\n\nnew_folder = smartsheet.folders.create_in_folder(\n\
\ folder_id: 7960873114331012,\n body: body\n)\n"
/folders/{folderId}/move:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D/parameters/1'
post:
summary: Move Folder
description: Moves a folder.
tags:
- folders
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
operationId: move-folder
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
description: New folder destination.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: Result object containing a Folder object for the new folder
destination.
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D~1move/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/folders/{folderId}/move \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-d '{\n \"destinationType\": \"folder\",\n \"\
destinationId\": 7960873114331012\n}' \\\n-X POST\n"
- lang: C#
source: "// Specify destination\nContainerDestination destination = new ContainerDestination\
\ {\n DestinationId = 7960873114331012, // long destinationFolderId\n\
\ DestinationType = DestinationType.FOLDER,\n};\n\n// Move folder\nFolder\
\ folder = smartsheet.FolderResources.MoveFolder(\n 4509918431602564, \
\ // long folderId\n destination\n);\n"
- lang: Java
source: "// Specify destination\nContainerDestination destination = new ContainerDestination()\n\
\ .setDestinationType(DestinationType.FOLDER)\n .setDestinationId(7960873114331012L);\n\
\n// Move folder\nFolder folder = smartsheet.folderResources().moveFolder(\n\
\ 4509918431602564L, // long folderId\n \
\ destination\n );\n"
- lang: JavaScript
source: "// Set destination information\nvar body = {\n destinationType:\
\ \"folder\",\n destinationId: 7960873114331012\n};\n\n// Set options\n\
var options = {\n folderId: 4509918431602564,\n body: body\n};\n\n// Move\
\ folder\nsmartsheet.folders.moveFolder(options)\n .then(function(folder)\
\ {\n console.log(folder);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "folder = smartsheet_client.Folders.move_folder(\n 4509918431602564,\
\ # folder_id to be moved\n smartsheet.models.ContainerDestination({\n\
\ 'destination_id': 7960873114331012, # destination folder_id\n \
\ 'destination_type': 'folder'\n })\n)\n"
- lang: Ruby
source: "# Specify destination information\nbody = {\n destination_type:\
\ 'workspace',\n destination_id: 7960873114331012\n}\n\n# Move folder\n\
response = smartsheet.folders.move(\n folder_id: 4509918431602564,\n body:\
\ body\n)\n"
/folders/{folderId}/sheets:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D/parameters/1'
post:
summary: Create Sheet in Folder
description: >
Creates a sheet from scratch or from the specified template in the
specified folder.
operationId: create-sheet-in-folder
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- name: include
in: query
required: false
description: |
Additional parameter to create a sheet from template.
A comma-separated list of elements to copy from the template.
schema:
type: string
enum:
- attachments
- cellLinks
- data
- discussions
- filters
- forms
- ruleRecipients
- rules
requestBody:
description: Sheet to create.
required: true
content:
application/json:
schema:
oneOf:
- type: object
description: Sheet to create from scratch using the specified columns.
properties:
columns:
type: array
items:
type: object
properties:
autoNumberFormat:
$ref: '#/components/schemas/Column/properties/autoNumberFormat'
contactOptions:
type: array
items:
$ref: '#/components/schemas/Column/properties/contactOptions/items'
description: Array of ContactOption objects to specify a
pre-defined list of values for the column. Column **type**
must be **CONTACT_LIST**.
options:
type: array
items:
type: string
description: Array of the options available for the column.
primary:
type: boolean
description: Returned only if the column is the Primary
Column (value = **true**).
symbol:
type: string
description: When applicable for **CHECKBOX** or **PICKLIST**
column types. See [Symbol Columns](../../tag/columnsRelated#section/Column-Types/Symbol-Columns).
systemColumnType:
type: string
enum:
- AUTO_NUMBER
- CREATED_BY
- CREATED_DATE
- MODIFIED_BY
- MODIFIED_DATE
description: See [System Columns](../../tag/columnsRelated#section/Column-Types).
title:
type: string
description: Column title.
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
description: See [Column Types](../../tag/columnsRelated#section/Column-Types)
width:
type: number
description: Display width of the column in pixels.
name:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/name'
- type: object
description: Sheet to create from template.
properties:
fromId:
description: Template Id from which to create the sheet.
type: number
name:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/name'
responses:
'200':
description: Result object containing a Sheet object for newly created sheet,
corresponding to what was specified in the request.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
oneOf:
- type: object
description: Sheet created from scratch using the specified
columns.
properties:
accessLevel:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/accessLevel'
columns:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/columns'
id:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/id'
name:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/name'
permalink:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/permalink'
- type: object
description: Sheet created from template.
properties:
accessLevel:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/accessLevel'
id:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/id'
name:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/name'
permalink:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/permalink'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "// Sample 1: Create sheet in folder\ncurl https://api.smartsheet.com/2.0/folders/{folderId}/sheets\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"name\":\"newsheet\",\"columns\"\
:[{\"title\":\"Favorite\",\"type\":\"CHECKBOX\",\"symbol\":\"STAR\"}, {\"\
title\":\"Primary Column\", \"primary\":true,\"type\":\"TEXT_NUMBER\"}]}'\n\
\n// Sample 2: Create sheet in folder from template\ncurl 'https://api.smartsheet.com/2.0/folders/{folderId}/sheets?include=data,attachments,discussions'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"name\":\"newsheet\", \"fromId\"\
: 7679398137620356}'\n\n"
- lang: C#
source: "// Sample 1: Create sheet in folder\n// Specify properties of the\
\ first column\nColumn columnA = new Column\n{\n Title = \"Favorite\",\n\
\ Primary = false,\n Type = ColumnType.CHECKBOX,\n Symbol = Symbol.STAR\n\
};\n\n// Specify properties of the second column\nColumn columnB = new Column\n\
{\n Title = \"Primary Column\",\n Primary = true,\n Type = ColumnType.TEXT_NUMBER\n\
};\n\n// Create sheet in folder (specifying the 2 columns to include in\
\ the sheet)\nSheet newSheet = smartsheet.FolderResources.SheetResources.CreateSheet(\n\
\ 3734419270854532, // long folderId\n new Sheet\n \
\ {\n Name = \"new sheet title\",\n Columns = new Column[] {\
\ columnA, columnB }\n }\n);\n\n// Sample 2: Create sheet in folder from\
\ template\n// Specify name for the sheet and Id of the template\nSheet\
\ sheetSpecification = new Sheet\n{\n Name = \"new sheet title\",\n FromId\
\ = 7679398137620356 // template Id\n};\n\n// Option 1: Omit 'include'\
\ parameter\nSheet newSheet = smartsheet.FolderResources.SheetResources.CreateSheetFromTemplate(\n\
\ 3734419270854532, // long folderId\n sheetSpecification,\n\
\ null // IEnumerable include\n\
);\n\n// Option 2: Include ATTACHMENTS, DATA, and DISCUSSIONS\nSheet newSheet\
\ = smartsheet.FolderResources.SheetResources.CreateSheetFromTemplate(\n\
\ 3734419270854532, // long folderId\n sheetSpecification,\n\
\ new TemplateInclusion[] {\n TemplateInclusion.ATTACHMENTS,\n TemplateInclusion.DATA,\n\
\ TemplateInclusion.DISCUSSIONS }\n);\n"
- lang: Java
source: "// Sample 1: Create sheet in folder\n// Specify properties of the\
\ first column\nColumn columnA = new Column()\n .setTitle(\"Favorite\"\
)\n .setType(ColumnType.CHECKBOX)\n .setSymbol(Symbol.STAR);\n\
\n// Specify properties of the second column\nColumn columnB = new Column()\n\
\ .setTitle(\"Primary Column\")\n .setType(ColumnType.TEXT_NUMBER)\n\
\ .setPrimary(true);\n\n// Create sheet in folder (specifying the\
\ 2 columns to include in the sheet)\nSheet newSheet = new Sheet();\n \
\ newSheet.setName(\"new sheet title\");\n newSheet.setColumns(Arrays.asList(columnA,\
\ columnB));\n\nsmartsheet.sheetResources().createSheetInFolder(\n \
\ 3734419270854532L, // long folderId\n newSheet\n );\n\
\n// Sample 2: Create sheet in folder from template\n// Specify name for\
\ the sheet and Id of the template\nSheet sheet = new Sheet();\nsheet.setFromId(7679398137620356L);\
\ // long templateId\nsheet.setName(\"newsheet\");\n\n// Omit 'include'\
\ parameter\nSheet results = smartsheet.sheetResources().createSheetInFolderFromTemplate(\n\
\ 3734419270854532L, // long folderId\n sheet,\n\
\ null // EnumSet\
\ includes\n );\n\n// Include ATTACHMENTS, DATA, and DISCUSSIONS\n\
Sheet results = smartsheet.sheetResources().createSheetInFolderFromTemplate(\n\
\ 3734419270854532L, // long folderId\n sheet,\n\
\ EnumSet.of(\n SheetTemplateInclusion.ATTACHMENTS,\n\
\ SheetTemplateInclusion.DATA,\n SheetTemplateInclusion.DISCUSSIONS)\n\
\ );\n\n"
- lang: JavaScript
source: "// Sample 1: Create sheet in folder\n// Specify sheet properties\n\
var sheet = {\n \"name\": \"newsheet\",\n \"columns\": [\n {\n \
\ \"title\": \"Favorite\",\n \"type\": \"CHECKBOX\",\n \"symbol\"\
: \"STAR\"\n },\n {\n \"title\": \"Primary Column\",\n \"\
primary\": true,\n \"type\": \"TEXT_NUMBER\"\n }\n ]\n};\n\n//\
\ Set options\nvar options = {\n folderId: 3734419270854532,\n body: sheet\n\
\ };\n\n// Create sheet in folder\nsmartsheet.sheets.createSheetInFolder(options)\n\
\ .then(function(newSheet) {\n console.log(newSheet);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n\n// Sample 2: Create sheet in folder\
\ from template\n// Specify the directive\nvar sheet = {\n \"name\": \"\
newsheet\",\n \"fromId\": 7679398137620356\n};\n\n// Set options\nvar options\
\ = {\n body: sheet,\n folderId: 3734419270854532\n};\n\n// Create sheet\
\ from template in the specified folder\nsmartsheet.sheets.createSheetFromExisting(options)\n\
\ .then(function(data) {\n console.log(data);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n\n"
label: Node.js
- lang: Python
source: "# Sample 1: Create sheet in folder\nsheet_spec = smartsheet.models.Sheet({\n\
\ 'name': 'newsheet',\n 'columns': [{\n 'title': 'Favorite',\n\
\ 'type': 'CHECKBOX',\n 'symbol': 'STAR'\n }, {\n \
\ 'title': 'Primary Column',\n 'primary': True,\n 'type':\
\ 'TEXT_NUMBER'\n }\n ]\n})\nresponse = smartsheet_client.Folders.create_sheet_in_folder(\n\
\ 3734419270854532, # folder_id\n sheet_spec)\nnew_sheet = response.result\n\
\n# Sample 2: Create sheet in folder from template\nresponse = smartsheet_client.Folders.create_sheet_in_folder_from_template(\n\
\ 3734419270854532, # folder_id\n smartsheet.models.Sheet({\n\
\ 'name': 'newsheet',\n 'from_id': 7679398137620356 # template_id\n\
\ })\n)\n\n"
- lang: Ruby
source: "# Sample 1: Create sheet in folder\nbody = {\n name: 'newsheet',\n\
\ columns: [\n {\n title: 'Favorite',\n type: 'CHECKBOX',\n\
\ symbol: 'STAR',\n width: 10\n },\n {\n title: 'Primary\
\ Column',\n type: 'TEXT_NUMBER',\n primary: true\n }\n ]\n\
}\n\nresponse = smartsheet.sheets.create_in_folder(\n folder_id: 3734419270854532,\n\
\ body: body\n)\nnew_sheet = response[:result]\n\n# Sample 2: Create sheet\
\ in folder from template\nbody = {\n name: 'newsheet',\n from_id: 7679398137620356\n\
}\n\nresponse = smartsheet.sheets.create_in_folder_from_template(\n folder_id:\
\ 3734419270854532,\n body: body\n)\nnew_sheet = response[:result]\n"
/folders/{folderId}/sheets/import:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D/parameters/1'
post:
summary: Import Sheet into Folder
description: >
Imports CSV or XLSX data into a new sheet in the specified folder.
Note the following:
* Both sheetName and the file name must use ASCII characters.
* The source data must be basic text. To include rich formula data, import
and create a sheet first, and then use Update Rows. To work with images, see
Cell Images.
* XLS is not supported. You must use XLSX.
* Hierarchical relationships between rows in an external file won't import.
operationId: import-sheet-into-folder
tags:
- import
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
parameters:
- name: Content-Disposition
in: header
description: >
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
schema:
type: string
example: attachment; filename="ProgressReport.docx"
- name: Content-Type
in: header
required: true
description: >
Required for POST request to import a sheet from CSV/XLSX file.
* For CSV files, use: Content-Type: text/csv
* For XLSX files, use: Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
schema:
type: string
enum:
- text/csv
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- name: sheetName
in: query
schema:
type: string
required: true
description: Desired name of the sheet.
- name: headerRowIndex
in: query
schema:
type: number
required: false
description: >
A zero-based integer indicating the row number to use for column
names. Rows before this are omitted.
If not specified, the default values are Column1, Column2, etc.
- name: primaryColumnIndex
in: query
schema:
type: number
default: 0
required: false
description: |
A zero-based integer indicating the column to designate as primary.
requestBody:
description: Binary content for the CSV / XLSX file.
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: Result object containing a Sheet object for imported sheet.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: object
description: Sheet imported from CSV / XLSX file.
properties:
accessLevel:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/accessLevel'
id:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/id'
name:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/name'
type:
description: Container type. Has 'sheet' value for the imported
sheet.
type: string
permalink:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/permalink'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/folders/{folderId}/sheets/import?sheetName=MarketingProgressReport&headerRowIndex=0&primaryColumnIndex=0\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Disposition:\
\ attachment\" \\\n-H \"Content-Type: text/csv\" \\\n-X POST \\\n--data-binary\
\ @ProgressReport.csv\n"
- lang: C#
source: "Sheet sheet = smartsheet.FolderResources.SheetResources.ImportXlsSheet(\n\
\ 8999900887877508, // folderId\n \"D:/ProgressReport.xlsx\",\n\
\ null, // sheetName defaults to file name unless specified\n\
\ 0, // headerRowIndex\n null \
\ // primaryColumnIndex\n);\n"
- lang: Java
source: "Sheet sheet = smartsheet.sheetResources().importXlsxInFolder(\n \
\ 8999900887877508L, // long folderId\n \"D:/ProgressReport.xlsx\"\
,\n \"MarketingProgressReport\",\n 0, \
\ // headerRowIndex\n 0 // primaryColumnIndex\n\
\ );\n"
- lang: JavaScript
source: "// Sample 1: Import CSV into folder\n// Set options\nvar options\
\ = {\n folderId: 8999900887877508,\n queryParameters: {\n sheetName:\
\ 'MarketingProgressReport'\n },\n path: \"D:/ProgressReport.csv\"\n};\n\
\n// Import CSV as sheet into folder\nsmartsheet.sheets.importCsvSheetIntoFolder(options)\n\
\ .then(function(attachment) {\n console.log(attachment);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n\n//Sample 2: Import XLSX into folder\n\
// Set options\nvar options = {\n folderId: 8999900887877508,\n queryParameters:\
\ {\n sheetName: 'MarketingProgressReport'\n },\n path: \"D:/ProgressReport.xlsx\"\
\n};\n\n// Import XLSX as sheet into Folder\nsmartsheet.sheets.importXlsxSheetIntoFolder(options)\n\
\ .then(function(attachment) {\n console.log(attachment);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "imported_sheet = smartsheet_client.Folders.import_xlsx_sheet(\n \
\ 8999900887877508, # folder_id\n 'D:/ProgressReport.xlsx',\n\
\ 'MarketingProgressReport', # sheet_name\n header_row_index=0\n)\n"
- lang: Ruby
source: "# Sample 1: Import from file into folder\nsmartsheet.sheets.import_from_file_into_folder(\n\
\ folder_id: 8999900887877508,\n file: sample_csv,\n file_type: :csv,\n\
\ file_length: sample_csv.size,\n params: {sheetName: 'MarketingProgressReport',\
\ headerRowIndex: 0, primaryColumnIndex: 0})\n\n# Sample 2: Import from\
\ file path into folder\nsmartsheet.sheets.import_from_file_path_into_folder(\n\
\ folder_id: 89999300887877508,\n path: 'D:\\sample.csv',\n file_type:\
\ :csv,\n params: {sheetName: 'MarketingProgressReport', headerRowIndex:\
\ 0, primaryColumnIndex: 0})\n"
/groups:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
operationId: list-groups
summary: List Org Groups
description: >
Gets a list of all groups in an organization account. To fetch the
members of an individual group, use the [Get
Group](../../tag/groups#operation/get-group) operation.
tags:
- groups
security:
- APIToken: []
- OAuth2:
- READ_USERS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/1'
- $ref: '#/paths/~1contacts/get/parameters/2'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: >
IndexResult object containing an array of [Group
objects](/section/Group-Object)
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: List of Groups
type: array
items:
type: object
properties:
id:
description: Group Id.
type: number
example: 4583173393803140
name:
description: Group name.
type: string
example: Group 1
description:
description: Group description.
type: string
example: My group
owner:
description: Group owner’s email address.
type: string
format: email
example: john.doe@smartsheet.com
ownerId:
description: Group owner's user Id.
type: number
example: 2331373580117892
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/groups \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult groups = smartsheet.GroupResources.ListGroups(\n\
\ null // PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult groups = smartsheet.groupResources().listGroups(\n\
\ null // PaginationParameters\n );\n"
- lang: JavaScript
source: "smartsheet.groups.listGroups()\n .then(function(groupList) {\n \
\ console.log(groupList);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Groups.list_groups(include_all=True)\n\
groups = response.data\n\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Groups.list_groups(\n\
\ page_size=10,\n page=1)\npages = response.total_pages\ngroups = response.data\n"
- lang: Ruby
source: "response = smartsheet.groups.list\ngroups = response[:data]\n"
post:
operationId: add-group
summary: Add Group
description: >
Creates a new group.
**_This operation is only available to group administrators and system administrators._**
tags:
- groups
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
requestBody:
description: >
[Group object](../../tag/groupsObjects#section/Group-Object), limited
to the following attributes:
* name (required) -- must be unique within the organization account
* description (optional)
* members (optional) -- array of [GroupMember objects](../../tag/groupMembersObjects#section/Group-Member-Object),
each limited to the following attribute:
* email
content:
application/json:
schema:
description: Create group request.
type: object
properties:
name:
description: |
**name** (required)
Must be unique within the organization account.
type: string
example: API-created group
description:
description: |
**description** (optional)
type: string
example: Group created via API
members:
type: array
items:
type: object
properties:
email:
description: Group member's email address.
type: string
format: email
example: john.doe@smartsheet.com
responses:
'200':
description: >
Result object, containing a [Group
object](../../tag/groupsObjects#section/Group-Object) for the newly
created group
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1groups/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
'400':
$ref: '#/paths/~1events/get/responses/400'
'401':
$ref: '#/paths/~1contacts/get/responses/401'
'500':
$ref: '#/paths/~1contacts/get/responses/500'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/groups \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n-H \"Content-Type: application/json\"\
\ \\\n-X POST \\\n-d '{ \"name\": \"API-created Group\", \"description\"\
: \"Group created via API\", \"members\": [{ \"email\": \"john.doe@smartsheet.com\"\
\ }]}'\n"
- lang: C#
source: "// Create group member\nGroupMember memberSpecification = new GroupMember\
\ { Email = \"john.doe@smartsheet.com\" };\n\n// Add member to group\nGroup\
\ groupSpecification = new Group\n{\n Name = \"API-created Group\",\n \
\ Description = \"Group created via API\",\n Members = new GroupMember[]\
\ { memberSpecification }\n};\n\n// Create group\nGroup newGroup = smartsheet.GroupResources.CreateGroup(groupSpecification);\n"
- lang: Java
source: "// Create group member\nGroupMember memberSpecification = new GroupMember();\n\
memberSpecification.setEmail(\"john.doe@smartsheet.com\");\n\n// Add member\
\ to group\nGroup groupSpecification = new Group();\ngroupSpecification.setDescription(\"\
Group created via API\")\n .setMembers(Arrays.asList(memberSpecification))\n\
\ .setName(\"API-created Group\");\n\n// Create group\nGroup newGroup\
\ = smartsheet.groupResources().createGroup(groupSpecification);\n"
- lang: JavaScript
source: "// Specify group\nvar group = {\n \"name\": \"API-created Group\"\
,\n \"description\": \"Group created via API\",\n \"members\": [\n \
\ {\n \"email\": \"john.doe@smartsheet.com\"\n }\n ]\n};\n\n//\
\ Set options\nvar options = {\n body: group\n};\n\n// Create group\nsmartsheet.groups.createGroup(options)\n\
\ .then(function(newGroup) {\n console.log(newGroup);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "new_group = smartsheet_client.Groups.create_group(\n smartsheet.models.Group({\n\
\ 'name': 'API-created Group',\n 'description': 'Group created via\
\ API',\n 'members': smartsheet.models.GroupMember({\n 'email':\
\ 'john.doe@smartsheet.com'\n })\n })\n)\n"
- lang: Ruby
source: "# List members of group\nbody = {\n name: 'API-created Group',\n\
\ description: 'Group created via API',\n members: [\n {\n email:\
\ 'john.doe@smartsheet.com'\n }\n ]\n}\n\n# Create group\nnew_group\
\ = smartsheet.groups.create(\n body: body\n)\n"
/groups/{groupId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: groupId
description: Group Id
in: path
required: true
schema:
type: number
get:
operationId: get-group
summary: Get Group
description: Gets information about and an array of [Group Members](../../tag/groupMembersObjects#section/Group-Member-Object)
for the group specified in the URL.
tags:
- groups
security:
- APIToken: []
- OAuth2:
- READ_USERS
responses:
'200':
description: >
[Group](/section/Group-Object) object that includes the list of
[GroupMember](../../tag/groupMembersObjects#section/Group-Member-Object)
objects
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1groups/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
- type: object
properties:
data:
description: List of Group Members
type: array
items:
type: object
properties:
id:
description: Group member's user Id.
type: number
example: 2331373580117892
email:
description: Group member's email address.
type: string
format: email
example: john.doe@smartsheet.com
firstName:
description: Group member's first name.
type: string
example: John
lastName:
description: Group member's last name.
type: string
example: Doe
name:
description: Group member's full name.
type: string
example: John Doe
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/groups/{groupId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Group group = smartsheet.GroupResources.GetGroup(\n 6932724448552836\
\ // long groupId\n);\n"
- lang: Java
source: "Group group = smartsheet.groupResources().getGroup(\n 6932724448552836L\
\ // long groupId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n id: 6932724448552836 // Id of\
\ Group\n};\n\n// Get group\nsmartsheet.groups.getGroup(options)\n .then(function(group)\
\ {\n console.log(group);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "group = smartsheet_client.Groups.get_group(\n 6932724448552836)\
\ # group_id\n# group is an instance of smartsheet.models.Group\n"
- lang: Ruby
source: "group = smartsheet.groups.get(\n group_id: 6932724448552836\n)\n"
put:
operationId: update-group
summary: Update Group
description: >
Updates the Group specified in the URL.
**_This operation is only available to group administrators and system administrators._**
tags:
- groups
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
requestBody:
description: >
Group object, limited to the following attributes:
* description (optional)
* name (optional) -- must be unique within the organization account
* ownerId (optional): Id of an admin user to whom the group ownership is
transferred
content:
application/json:
schema:
description: Updates group properties, including name, description,
and owner.
type: object
properties:
name:
description: |
name (Optional)
Must be unique within the organization account.
type: string
example: Renamed group
description:
description: Description (optional).
type: string
example: Some new description
ownerId:
description: >
ownerId (optional)
Id of an admin user to whom the group ownership is transferred.
type: number
example: 94094820842
responses:
'200':
description: Result object containing the [Group object](../../tag/groupsObjects#section/Group-Object)
for the updated group
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1groups~1%7BgroupId%7D/get/responses/200/content/application~1json/schema/allOf/0'
'400':
$ref: '#/paths/~1events/get/responses/400'
'500':
$ref: '#/paths/~1contacts/get/responses/500'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/groups/{groupId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X PUT \\\n-d '{ \"name\": \"Renamed Group\", \"description\": \"\
Some new description\" }'\n"
- lang: C#
source: "// Specify the name and description of the group\nGroup groupSpecification\
\ = new Group\n{\n Id = 2331373580117892,\n Name = \"Renamed Group\",\n\
\ Description = \"Some new description\"\n};\n\n// Update group\nGroup\
\ updatedGroup = smartsheet.GroupResources.UpdateGroup(groupSpecification);\n"
- lang: Java
source: "// Specify the name and description of the group\nGroup groupSpecification\
\ = new Group(2331373580117892L);\n groupSpecification.setDescription(\"\
Some new description\")\n .setName(\"Renamed Group\");\n\n// Update\
\ group\nGroup updatedGroup = smartsheet.groupResources().updateGroup(groupSpecification);\n"
- lang: JavaScript
source: "// Specify the name and description of the group\nvar group = {\n\
\ \"name\": \"Renamed Group\",\n \"description\": \"Some new description\"\
\n};\n\n// Set options\nvar options = {\n id: 2331373580117892, // Id of\
\ Group\n body: group\n };\n\n// Update group\nsmartsheet.groups.updateGroup(options)\n\
\ .then(function(updatedGroup) {\n console.log(updatedGroup);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_group = smartsheet_client.Groups.update_group(\n 2331373580117892,\
\ # group_id\n smartsheet.models.Group({\n 'name': 'Renamed Group',\n\
\ 'description': 'Some new description'\n })\n)\n"
- lang: Ruby
source: "# Specify the name and description of the group\nbody = {\n name:\
\ 'Renamed Group',\n description: 'Some new description',\n owner_id:\
\ 4583173393803140\n}\n\n# Update group\nupdated_group = smartsheet.groups.update(\n\
\ group_id: 2331373580117892,\n body: body\n)\n"
delete:
operationId: delete-group
summary: Delete Group
description: >
Deletes the group specified in the URL.
**_This operation is only available to group administrators and system administrators._**
tags:
- groups
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
responses:
'200':
description: >
**_This operation is asynchronous,_** _meaning group members may
retain their sharing access for a brief period of time after the
call returns. For small groups with limited sharing, the operation
should complete quickly (within a few seconds). For large groups
with many shares, this operation could possibly take more than a
minute to complete._
content:
application/json:
schema:
$ref: '#/paths/~1groups~1%7BgroupId%7D/put/responses/200/content/application~1json/schema/allOf/0'
'401':
$ref: '#/paths/~1contacts/get/responses/401'
'404':
$ref: '#/paths/~1contacts/get/responses/404'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/groups/{groupId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.GroupResources.DeleteGroup(\n 6932724448552836 \
\ // long groupId\n);\n"
- lang: Java
source: "smartsheet.groupResources().deleteGroup(\n 6932724448552836L\
\ // long groupId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n id: 6932724448552836 // Id of\
\ Group\n};\n\n// Delete group\nsmartsheet.groups.deleteGroup(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Groups.delete_group(\n 6932724448552836) \
\ # group_id\n"
- lang: Ruby
source: "smartsheet.groups.delete(\n group_id: 4583173393803140\n)\n"
/groups/{groupId}/members:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1groups~1%7BgroupId%7D/parameters/1'
post:
operationId: add-group-members
summary: Add Group Members
description: >
Adds one or more members to a group.
**_This operation supports both single-object and bulk semantics. For more
information, see Optional Bulk Operations._**
If called with a single [GroupMember object](../../tag/groupMembersObjects),
and that group member already exists, error code **1129** is returned.
If called with an array of [GroupMember objects](../../tag/groupMembersObjects),
any users specified in the array that are already group members are ignored
and omitted from the response.
**_This operation is only available to group administrators and system administrators._**
tags:
- groupMembers
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1groups~1%7BgroupId%7D/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
- type: array
items:
$ref: '#/paths/~1groups~1%7BgroupId%7D~1members/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: >
Returns a Result object containing the members added to the group --
either a single [GroupMember](/section/Group-Member-Object) or array
of [GroupMember](/section/Group-Member-Object) objects,
corresponding to what was specified in the request.
**_This operation is asynchronous,_** _meaning the users may not yet have
sharing access to sheets for a period of time after this operation returns.
For small groups with limited sharing, the operation should complete quickly
(within a few seconds). For large groups with many shares, this operation
could possibly take more than a minute to complete._
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1groups~1%7BgroupId%7D~1members/post/requestBody/content/application~1json/schema/oneOf/0'
- type: array
items:
$ref: '#/paths/~1groups~1%7BgroupId%7D~1members/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: >
If an error occurs because the request specified one or more
alternate email addresses, please retry using the primary email
address.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/groups/{groupId}/members \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{ \"email\": \"jane.doe@smartsheet.com\"\
\ }]'\n"
- lang: C#
source: "// Create group member\nGroupMember memberSpecification = new GroupMember\
\ { Email = \"jane.doe@smartsheet.com\" };\n\n// Add members to group\n\
IList newMembers = smartsheet.GroupResources.AddGroupMembers(\n\
\ 7917992160847748, // long groupId\n new GroupMember[] { memberSpecification\
\ }\n);\n"
- lang: Java
source: "// Create group member\nGroupMember memberSpecification = new GroupMember();\n\
\ memberSpecification.setEmail(\"jane.doe@smartsheet.com\");\n\n\
// Add members to group\nList newMembers = smartsheet.groupResources().memberResources().addGroupMembers(\n\
\ 7917992160847748L, // long groupId\n Arrays.asList(memberSpecification)\n\
\ );\n"
- lang: JavaScript
source: "// Specify group members\nvar members = [{ \"email\": \"jane.doe@smartsheet.com\"\
\ }];\n\n// Set options\nvar options = {\n groupId: 7917992160847748,\n\
\ body: members\n };\n\n// Add members to group\nsmartsheet.groups.addGroupMembers(options)\n\
\ .then(function(newMembers) {\n console.log(newMembers);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "new_members = smartsheet_client.Groups.add_members(\n 7917992160847748,\
\ # group_id\n [smartsheet.models.GroupMember({'email': 'jane.doe@smartsheet.com'})]\n\
)\n"
- lang: Ruby
source: "body = {\n email: 'jane.doe@smartsheet.com'\n}\n\nnew_members =\
\ smartsheet.groups.add_members(\n group_id: 7917992160847748,\n body:\
\ body\n)\n"
/groups/{groupId}/members/{userId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1groups~1%7BgroupId%7D/parameters/1'
- name: userId
description: User Id
in: path
required: true
schema:
type: number
delete:
operationId: delete-group-members
summary: Delete Group Members
description: >
Removes a member from a group.
**_This operation is only available to group administrators and system administrators._**
tags:
- groupMembers
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
responses:
'200':
description: >
**_This operation is asynchronous,_** _meaning the users may not yet
have sharing access to sheets for a period of time after this
operation returns. For small groups with limited sharing, the
operation should complete quickly (within a few seconds). For large
groups with many shares, this operation could possibly take more
than a minute to complete._
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/groups/{groupId}/members/{userId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.GroupResources.RemoveGroupMember(\n 7917992160847748,\
\ // long groupId\n 1539725208119172 // long userId\n\
);\n"
- lang: Java
source: "smartsheet.groupResources().memberResources().deleteGroupMember(\n\
\ 7917992160847748L, // long groupId\n 1539725208119172L)\
\ // long userId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n groupId: 7917992160847748,\n \
\ userId: 1539725208119172\n};\n\n// Remove member from group\nsmartsheet.groups.removeGroupMember(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Groups.remove_member(\n 7917992160847748, \
\ # group_id\n 1539725208119172) # group_member_id\n"
- lang: Ruby
source: "smartsheet.groups.remove_member(\n group_id: 4583173393803140,\n\
\ user_id: 48569348493401200\n)\n"
/home:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Contents
description: Gets a nested list of all Home objects, including dashboards, folders,
reports, sheets, templates, and workspaces, as shown on the "Home" tab.
tags:
- home
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: list-home-contents
responses:
'200':
description: A single Home object.
content:
application/json:
schema:
description: All objects a user has access to, including dashboards,
folders, reports, sheets, templates, and workspaces.
type: object
properties:
folders:
type: array
items:
$ref: '#/components/schemas/Folder/properties/folders/items'
reports:
type: array
items:
$ref: '#/components/schemas/Folder/properties/reports/items'
sheets:
type: array
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
sights:
type: array
items:
$ref: '#/components/schemas/Folder/properties/sights/items'
templates:
type: array
items:
$ref: '#/components/schemas/Folder/properties/templates/items'
workspaces:
type: array
items:
$ref: '#/components/schemas/Home/properties/workspaces/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/home?include=source' \\\n-H\
\ \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Sample 1: Omit 'include' parameters\nHome home = smartsheet.HomeResources.GetHome(\n\
\ null // IEnumerable includes\n);\n\n//\
\ Sample 2: Specify 'include' parameter with value of \"SOURCE\"\nHome home\
\ = smartsheet.HomeResources.GetHome(\n new HomeInclusion[] { HomeInclusion.SOURCE\
\ }\n);\n"
- lang: Java
source: "// Sample 1: Omit 'include' parameter\nHome home = smartsheet.homeResources().getHome(\n\
\ null // EnumSet includes\n );\n\
\n// Sample 2: Specify 'include' parameter with value of \"SOURCE\"\nHome\
\ home = smartsheet.homeResources().getHome(EnumSet.of(SourceInclusion.SOURCE)));\n"
- lang: JavaScript
source: "smartsheet.home.listContents()\n .then(function(contents) {\n \
\ console.log(contents);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "contents = smartsheet_client.Home.list_all_contents(include='source')\n"
- lang: Ruby
source: "contents = smartsheet.home.list\n"
/home/folders:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Folders in Home
description: Gets a list of folders in your Home tab. The list contains an abbreviated
Folder object for each folder.
tags:
- home
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: home-list-folders
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: IndexResult object containing an array of Folder objects.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Folder/properties/folders/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/home/folders \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult folders =\
\ smartsheet.HomeResources.FolderResources.ListFolders(\n null \
\ // PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult folders = smartsheet.homeResources().folderResources().listFolders(\n\
\ null // PaginationParameters\n );\n"
- lang: JavaScript
source: "smartsheet.home.listFolders()\n .then(function(folderList) {\n \
\ console.log(folderList);\n })\n .catch(function(error) {\n console.log(error);\n\
\ })\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Home.list_folders(include_all=True)\n\
home_sheets_folders = response.data\n\n# Sample 2: Paginate the list\nresponse\
\ = smartsheet_client.Home.list_folders(\n page_size=5,\n page=1)\npages\
\ = response.total_pages\nfolders = response.data\n"
- lang: Ruby
source: "response = smartsheet.folders.list\nfolders = response[:data]\n"
post:
summary: Create Folder
description: |
Creates a new folder.
operationId: create-home-folder
tags:
- home
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
description: Folder to create.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1home~1folders/get/responses/200/content/application~1json/schema/allOf/1/properties/result/items'
responses:
'200':
description: Result object containing a Folder object for newly created
folder.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1home~1folders/get/responses/200/content/application~1json/schema/allOf/1/properties/result/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1home~1folders/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/home/folders \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X POST \\\n-d '{\"name\": \"New folder\"}'\n"
- lang: C#
source: "// Set folder name\nFolder folderSpecification = new Folder { Name\
\ = \"New folder\" };\n\n// Create folder in \"Sheets\" folder (Home)\n\
Folder newFolder = smartsheet.HomeResources.FolderResources.CreateFolder(folderSpecification);\n"
- lang: Java
source: "// Set folder name\nFolder folderSpecification = new Folder();\n\
folderSpecification.setName(\"New Folder\");\n\n// Create folder in \"Sheets\"\
\ folder (Home)\nFolder newFolder = smartsheet.homeResources().folderResources().createFolder(folderSpecification);\n"
- lang: JavaScript
source: "// Set folder name\nvar folder = {\n \"name\": \"New folder\"\n\
};\n\n// Set options\nvar options = {\n body: folder\n};\n\n// Create folder\
\ in \"Sheets\" folder (Home)\nsmartsheet.home.createFolder(options)\n \
\ .then(function(newFolder) {\n console.log(newFolder);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "new_folder = smartsheet_client.Home.create_folder('New Folder')\n"
- lang: Ruby
source: "body = {\n name: 'New Folder'\n}\n\nnew_folder = smartsheet.folders.create(body:\
\ body)\n"
/imageurls:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1favorites/post/parameters/0'
post:
operationId: listImageUrls
summary: List Image URLs
description: Gets a list of URLs that can be used to retrieve the specified
cell images.
tags:
- cellImages
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ImageUrlMap/properties/imageUrls/items'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- type: object
properties:
imageUrls:
type: array
items:
$ref: '#/components/schemas/ImageUrlMap/properties/imageUrls/items'
urlExpiresInMillis:
description: Milliseconds before the URLs within imageUrls expire.
type: number
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/imageurls \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X POST \\\n-d '[{\"imageId\": \"e1znCxhuZo_soEJtUmmX_A\",\"height\"\
:40,\"width\": 20},{\"imageId\": \"g2jdKdfhQa_abKJmPnhC_B\",\"height\":100,\"\
width\": 50}]'\n"
- lang: C#
source: "// Build list of image urls\nImageUrl[] imageUrls = new ImageUrl[]\
\ { new ImageUrl { ImageId = \"jpbGklqdfZuL4Jw-kZhdZA\" } };\n\nstring temporaryUrl\
\ = smartsheet.ImageUrlResources.GetImageUrls(imageUrls).ImageUrls[0].Url;\n"
- lang: Java
source: "// Build list of image urls\nImageUrl imageUrl = new ImageUrl()\n\
\ .setImageId(\"jpbGklqdfZuL4Jw-kZhdZA\");\n List\
\ imageUrls = Arrays.asList(imageUrl);\n\n String temporaryUrl =\
\ smartsheet.imageUrlResources().getImageUrls(imageUrls).getImageUrls().get(0).getUrl();\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n body: [{\n imageId: \"jpbGklqdfZuL4Jw-kZhdZA\"\
,\n width: 256,\n height: 256\n }]\n};\n\n// List image URLs\nsmartsheet.images.listImageUrls(options)\n\
\ .then(function(temporaryUrls) {\n console.log(temporaryUrls);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "imageUrl = smartsheet.models.ImageUrl(\n {\n \"imageId\": 'jpbGklqdfZuL4Jw-kZhdZA',\n\
\ \"height\": 256,\n \"width\": 256\n }\n)\n\nresponse = smartsheet_client.Images.get_image_urls([imageUrl])\n\
url = response.image_urls[0].url\n"
- lang: Ruby
source: "body = [\n {\n image_id: 'jpbGklqdfZuL4Jw-kZhdZA',\n height:\
\ 100,\n width: 100\n }\n]\n\nimage_urls = smartsheet.sheets.list_image_urls(\n\
\ body: body\n)\n"
/reports:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
operationId: getReports
summary: Get Reports
description: Gets a list of all Reports that the user has access to.
tags:
- reports
security:
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/1'
responses:
'200':
description: >
IndexResult object containing an array of Report objects with a
subset of attributes
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: List of Report Objects limited to the properties,
id, accessLevel, name, and permalink.
type: array
items:
$ref: '#/components/schemas/Folder/properties/reports/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/reports\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "PaginatedResult reports = smartsheet.ReportResources.ListReports(\n\
\ null, // PaginationParameters\n null //\
\ Nullable modifiedSince = null\n);\n"
- lang: Java
source: "PagedResult reports = smartsheet.reportResources().listReports(\n\
\ null, // PaginationParameters\n null \
\ // Date modifiedSince\n );\n"
- lang: JavaScript
source: "smartsheet.reports.listReports()\n .then(function(reportList) {\n\
\ console.log(reportList);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Reports.list_reports(include_all=True)\n\
reports = response.data\n"
- lang: Ruby
source: "response = smartsheet.reports.list\nreports = response[:data]\n"
/reports/{reportId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: Accept
in: header
description: The Accept request-header field can be used to specify certain
media types which are acceptable for the response.
schema:
type: string
required: false
- name: reportId
in: path
schema:
type: number
required: true
description: reportID of the report being accessed.
get:
summary: Get Report
description: Gets a report based on the specified ID
operationId: getReport
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of optional elements to include in the
response:
* **attachments**
* **discussions**
* **proofs**
* **format**
* **objectValue** - when used in combination with a level query parameter,
includes the email addresses for multi-contact data
* **scope** - adds the report's scope to the response
* **source** - adds the Source object indicating which report the report
was created from, if any
* **sourceSheets**
schema:
type: string
enum:
- attachments
- discussions
- proofs
- format
- objectValue
- scope
- source
- sourceSheets
- name: exclude
in: query
required: false
description: >
A comma-separated list of optional elements to not include in the
response
schema:
type: string
enum:
- linkInFromCellDetails
- linksOutToCellsDetails
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/3'
- name: level
in: query
required: false
description: 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=3).
schema:
type: integer
default: 0
tags:
- reports
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: The Report that was loaded.
content:
application/json:
schema:
$ref: '#/components/schemas/Folder/properties/reports/items'
application/vnd.ms-excel:
schema:
type: string
format: binary
description: The Report in Excel format
text/csv:
schema:
type: string
format: binary
description: The Report in CSV format
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "// Sample 1: Get report\ncurl https://api.smartsheet.com/2.0/reports/{reportId}?level=3&include=objectValue\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n\n// Sample\
\ 2: Get report as Excel\ncurl https://api.smartsheet.com/2.0/reports/{reportId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Accept:\
\ application/vnd.ms-excel\" \\\n-o output.xlsx\n\n// Sample 3: Get report\
\ as CSV\ncurl https://api.smartsheet.com/2.0/reports/{reportId} \\\n-H\
\ \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Accept: text/csv\"\
\ \\\n-o output.csv\n\n"
- lang: C#
source: "// Sample 1: Omit 'include', 'pageSize', and 'page' parameters\n\
Report report = smartsheet.ReportResources.GetReport(\n 4583173393803140,\
\ // long reportId\n null, // IEnumerable\
\ include\n null, // int pageSize\n null \
\ // int page\n);\n\n// Sample 2: Specify 'include' parameter\
\ with value of \"ATTACHMENTS\" and \"DISCUSSIONS\", 'pageSize' parameter\
\ with value of \"500\", and 'page' of value \"2\"\nReport report = smartsheet.ReportResources.GetReport(\n\
\ 4583173393803140, // long reportId\n new ReportInclusion[]\
\ {\n ReportInclusion.ATTACHMENTS,\n ReportInclusion.DISCUSSIONS\n\
\ },\n 500, // int pageSize\n 2 \
\ // int page\n);\n\n// Sample 3: Get report as Excel\nsmartsheet.ReportResources.GetReportAsExcel(\n\
\ 3882962191181700, // long reportId\n outputStream \
\ // BinaryWriter\n);\n\n// Sample 4: Get report as CSV\n\
smartsheet.ReportResources.GetReportAsCSV(\n 3882962191181700, \
\ // long reportId\n outputStream // BinaryWriter\n);\n\
\n"
- lang: Java
source: "// Sample 1: Omit 'include', 'pageSize', and 'page' parameters\n\
Report report = smartsheet.reportResources().getReport(\n 4583173393803140L,\
\ // long reportId\n null, // EnumSet\
\ includes\n null, // int pageSize\n null\
\ // int page\n );\n\n// Sample 2: Specify 'include'\
\ parameter with value of \"ATTACHMENTS\" and \"DISCUSSIONS\", 'pageSize'\
\ parameter with value of \"500\", and 'page' of value \"2\"\nReport report\
\ = smartsheet.reportResources().getReport(\n 4583173393803140L,\
\ // long reportId\n EnumSet.of(\n ReportInclusion.ATTACHMENTS,\n\
\ ReportInclusion.DISCUSSIONS),\n 500, \
\ // int pageSize\n 2 // int page\n \
\ );\n\n// Sample 3: Get report as Excel\nsmartsheet.reportResources().getReportAsExcel(\n\
\ 3882962191181700L, // long reportId\n outputStream\n\
\ );\n\n// Sample 4: Get report as CSV\nsmartsheet.reportResources().getReportAsCsv(\n\
\ 3882962191181700L, // long reportId\n outputStream\n\
\ );\n\n\n"
- lang: JavaScript
source: "// Sample 1: Get report\n// Set options\nvar options = {\n id: 4583173393803140\
\ // Id of Report\n};\n\n// Get report\nsmartsheet.reports.getReport(options)\n\
\ .then(function(report) {\n console.log(report);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n\n// Sample 2: Get report as Excel\n\
var fs = require(\"fs\")\n\n// Set options\nvar options = {\n id: 3882962191181700\
\ // Id of Report\n};\n\n// Get sheet\nsmartsheet.reports.getReportAsExcel(options)\n\
\ .then(function(fileContents) {\n // Write report to file\n fs.writeFile('output.xlsx',\
\ fileContents, 'binary', (err) => {\n if (err) throw err;\n console.log('The\
\ report has been saved!');\n });\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n\n// Sample 3: Get report as CSV\nvar fs\
\ = require(\"fs\")\n\n// Set options\nvar options = {\n id: 3882962191181700\
\ // Id of Report\n};\n\n// Get sheet\nsmartsheet.reports.getReportAsCSV(options)\n\
\ .then(function(fileContents) {\n // Write report to file\n fs.writeFile('output.csv',\
\ fileContents, (err) => {\n if (err) throw err;\n console.log('The\
\ report has been saved!');\n });\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: Get report\nreport = smartsheet_client.Reports.get_report(\n\
\ 4583173393803140) # report_id\n\n# Sample 2: Get report as Excel\n\
# Download file with filename suggested by API\nsmartsheet_client.Reports.get_report_as_excel(\n\
\ 3882962191181700, # report_id\n download_folder_path\n)\n\n# Specify\
\ custom filename for the downloaded file\nsmartsheet_client.Reports.get_report_as_excel(\n\
\ 3882962191181700, # report_id\n download_folder_path,\n 'MyFileName.xslx'\n\
)\n\n# Sample 3: Get report as CSV\n# Download file with filename suggested\
\ by API\nsmartsheet_client.Reports.get_report_as_csv(\n 3882962191181700,\
\ # report_id\n download_folder_path\n)\n\n# Specify custom filename\
\ for the downloaded file\nsmartsheet_client.Reports.get_report_as_csv(\n\
\ 3882962191181700, # report_id\n download_folder_path,\n 'CallMeAl.csv'\n\
)\n\n"
- lang: Ruby
source: "# Sample 1: Get report\nreport = smartsheet.reports.get(\n report_id:\
\ 4583173393803140\n)\n\n# Sample 2: Get report as Excel\nfile_contents\
\ = smartsheet.reports.get_as_excel(\n report_id: 4583173393803140\n)\n\
\nFile.open('output.xlsx', 'w') {|f| f.write(file_contents)}\n\n# Sample\
\ 3: Get report as CSV\nfile_contents = smartsheet.reports.get_as_csv(\n\
\ report_id: 4583173393803140\n)\n\nFile.open('output.csv', 'w') {|f| f.write(file_contents)}\n\
\n\n"
/reports/{reportId}/emails:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1reports~1%7BreportId%7D/parameters/2'
post:
summary: Send report via email
description: Sends the report as a PDF attachment via email to the designated
recipients
operationId: sendReportViaEmail
tags:
- reports
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProofRequestBody/allOf/0'
type: object
properties:
format:
description: >
One of the following values: **EXCEL**, **PDF**, or
**PDF_GANTT**.
type: string
formatDetails:
$ref: '#/components/schemas/SheetEmail/properties/formatDetails'
responses:
'200':
description: Result Object
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/reports/{reportId}/emails \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"sendTo\" : [{\"email\": \"john.doe@smartsheet.com\"\
}, {\"groupId\": 2258118617917316}], \"subject\": \"Check these rows out!\"\
, \"message\": \"Here are the rows I mentioned in our meeting\", \"ccMe\"\
: false, \"format\": \"PDF\", \"formatDetails\": {\"paperSize\": \"A4\"\
}}'\n"
- lang: C#
source: "// Specify recipients\nRecipient[] recipientSpecification = new Recipient[]\
\ {\n new Recipient { Email = \"john.doe@smartsheet.com\" },\n new Recipient\
\ { GroupId = 2258118617917316 }\n};\n\n// Configure email\nSheetEmail sheetEmail\
\ = new SheetEmail {\n SendTo = recipientSpecification,\n Subject = \"\
Check this report out!\",\n Message = \"Here is the report I mentioned\
\ in our meeting\",\n CcMe = false,\n Format = SheetEmailFormat.PDF,\n\
\ FormatDetails = new FormatDetails { PaperSize = PaperSize.A4 }\n};\n\n\
// Send report via email\nsmartsheet.ReportResources.SendReport (8130994621441924,\
\ sheetEmail); // long reportId\n"
- lang: Java
source: "// Specify an individual recipient\nRecipientEmail recipientEmail\
\ = new RecipientEmail()\n .setEmail(\"john.doe@smartsheet.com\"\
);\n\n// Specify a group recipient\nRecipientGroup recipientGroup = new\
\ RecipientGroup()\n .setGroupId(2258118617917316L);\n\n// Set recipients\n\
List recipientList = Arrays.asList(\n recipientEmail,\n\
\ recipientGroup\n );\n\n// Set format details\nFormatDetails\
\ formatDetails = new FormatDetails()\n .setPaperSize(PaperSize.A0);\n\
\n// Configure email\nSheetEmail emailSpecification = new SheetEmail();\n\
emailSpecification.setFormat(SheetEmailFormat.PDF);\nemailSpecification.setFormatDetails(formatDetails)\n\
\ .setSendTo(recipientList)\n .setSubject(\"Check this report\
\ out!\")\n .setMessage(\"Here is the report I mentioned in our meeting\"\
)\n .setCcMe(false);\n\n// Send report via email\nsmartsheet.reportResources().sendReport(\n\
\ 8130994621441924L, // long reportId\n emailSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Configure email\nvar email = {\n \"sendTo\": [\n {\n \
\ \"email\": \"john.doe@smartsheet.com\"\n },\n {\n \"groupId\"\
: 2258118617917316\n }\n ],\n \"subject\": \"Check these rows out!\"\
,\n \"message\": \"Here are the rows I mentioned in our meeting\",\n \"\
ccMe\": false,\n \"format\": \"PDF\",\n \"formatDetails\": {\n \"paperSize\"\
: \"A4\"\n }\n};\n\n// Set options\nvar options = {\n body: email,\n \
\ reportId: 8130994621441924\n};\n\n// Send report via email\nsmartsheet.reports.sendReportViaEmail(options)\n\
\ .then(function(data) {\n console.log(data);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Reports.send_report(\n 8130994621441924,\
\ # report_id\n smartsheet.models.SheetEmail({\n 'send_to': smartsheet.models.Recipient({\n\
\ 'email': 'john.doe@smartsheet.com'\n }),\n 'subject': 'Check\
\ this report out!',\n 'message': 'Here is the report I mentioned in\
\ our meeting.',\n 'cc_me': False,\n 'format': 'PDF',\n 'format_details':\
\ smartsheet.models.FormatDetails({\n 'paper_size': 'A4'\n })\n\
\ })\n)\n"
- lang: Ruby
source: "body = {\n send_to: [\n {\n email: 'john.doe@smartsheet.com'\n\
\ },\n {\n group_id: 3051008235464580\n }\n ],\n subject:\
\ 'Check out this report!',\n message: 'Here is the report I mentioned\
\ in our meeting',\n cc_me: false,\n format: 'PDF',\n format_details:\
\ {\n paper_size: 'LEGAL'\n }\n}\n\nresponse = smartsheet.reports.send_via_email(\n\
\ report_id: 4583173393803140,\n body: body\n)\n"
/reports/{reportId}/publish:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1reports~1%7BreportId%7D/parameters/2'
get:
summary: Gets a Report's publish settings
description: Get a Report's publish settings based on the specified ID
operationId: getReportPublish
tags:
- reports
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: The Report's publish settings
content:
application/json:
schema:
type: object
properties:
readOnlyFullAccessibleBy:
description: >
Indicates who can access the 'Read-Only Full' view of the
published report:
* If **ALL**, it is available to anyone who has the link.
* If **ORG**, it is available only to members of the report
owner's Smartsheet organization account.
* If **SHARED**, it is available only to users shared to the
item.
Only returned in a response if **readOnlyFullEnabled** = **true**.
type: string
readOnlyFullDefaultView:
description: >
Indicates which view the user has set for a read-only,
default view of the published report. Must be one of
the following values: **CALENDAR**, **CARD**, or **GRID**.
type: string
readOnlyFullEnabled:
description: >
(Required) If **true**, a rich version of the report is
published with the ability to download row
attachments and discussions.
type: boolean
readOnlyFullShowToolbar:
deprecated: true
description: >
Indicates whether the left nav toolbar is displayed. The
default, or **true**, is to display the toolbar.
If **false**, hides the toolbar.
type: boolean
readOnlyFullUrl:
description: >
URL for 'Read-Only Full' view of the published report.
Only returned in a response if **readOnlyFullEnabled** = **true**.
type: string
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/reports/{reportId}/publish \\\
\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "smartsheet.ReportResources.GetPublishStatus(\n 3901932860401540\
\ // reportId\n);\n"
- lang: Java
source: "smartsheet.reportResources().getPublishStatus(\n 3901932860401540L\
\ // reportId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n reportId: 3901932860401540\n};\n\
\n// Get report publish status\nsmartsheet.reports.getReportPublishStatus(options)\n\
\ .then(function(status) {\n console.log(status);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "status = smartsheet_client.Reports.get_publish_status(\n 1653067851556740)\
\ # report_id\n"
- lang: Ruby
source: "status = smartsheet.reports.get_publish_status(\n report_id: 4583173393803140\n\
)\n"
put:
summary: Set a Report's publish status
description: Sets the publish status of the report and returns the new status,
including the URL of any enabled publishing.
operationId: SetReportPublish
tags:
- reports
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1publish/get/responses/200/content/application~1json/schema'
responses:
'200':
description: ReportPublish object
content:
application/json:
schema:
allOf:
- type: object
allOf:
- type: object
properties:
message:
description: Message that indicates the outcome of the request.
(One of SUCCESS or PARTIAL_SUCCESS.)
type: string
enum:
- PARTIAL_SUCCESS
- SUCCESS
example: SUCCESS
resultCode:
description: |-
* '0' Success
* '3' Partial Success of Bulk Operation
type: number
enum:
- 0
- 3
properties:
failedItems:
description: Array of BulkItemFailure objects which represents
the items that failed to be added or updated. See [Partial
Success](/partial-success) for more information. Applicable
only for bulk operations that support partial success.
type: array
items:
$ref: '#/components/schemas/Result/allOf/0/properties/failedItems/items'
nullable: true
- type: object
properties:
result:
$ref: '#/paths/~1reports~1%7BreportId%7D~1publish/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1publish/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/reports/{reportId}/publish \\\
\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{\"readOnlyFullEnabled\": true,\
\ \"readOnlyFullAccessibleBy\": \"ORG\"}'\n"
- lang: C#
source: "ReportPublish reportPublish = new ReportPublish();\nreportPublish.ReadOnlyFullEnabled\
\ = true;\nreportPublish.ReadOnlyFullAccessibleBy = \"ALL\";\nsmartsheet.ReportResources.UpdatePublishStatus(\n\
\ 1653087851556740, // reportId\n reportPublish\n);\n"
- lang: Java
source: "ReportPublish reportPublish = new ReportPublish();\nreportPublish.setReadOnlyFullEnabled(true);\n\
reportPublish.setReadOnlyFullAccessibleBy(\"ALL\");\nsmartsheet.reportResources().updatePublishStatus(\n\
\ 1653087851556740L, // reportId\n reportPublish\n \
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n reportId: 1653087851556740,\n\
\ body: {\n readOnlyFullEnabled: true,\n readOnlyFullAccessibleBy:\
\ \"ALL\"\n }\n};\n\n// Set report publish status\nsmartsheet.reports.setReportPublishStatus(options)\n\
\ .then(function(status) {\n console.log(status);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Reports.set_publish_status(\n 1653067851556740,\
\ # report_id\n smartsheet.models.ReportPublish({\n 'read_only_full_enabled':\
\ True\n })\n)\n"
- lang: Ruby
source: "# Set options\nbody = {\n read_only_full_enabled: true,\n read_only_full_accessible_by:\
\ 'ORG'\n}\n\n# Set report publish status\nstatus = smartsheet.reports.set_publish_status(\n\
\ report_id: 4583173393803140,\n body: body\n)\n"
/reports/{reportId}/shares:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1reports~1%7BreportId%7D/parameters/2'
post:
summary: Share Report
description: Shares a Report with the specified users and groups.
operationId: share-report
tags:
- sharing
- reports
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
parameters:
- name: sendEmail
in: query
description: Either true or false to indicate whether to notify the user by
email. Default is false.
required: false
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
properties:
id:
description: >
Share Id.
**NOTE**: unlike other Smartsheet object Ids, this Id is an
alphanumeric string.
type: string
groupId:
description: Group Id if the share is a group share, else null.
type: number
userId:
description: User Id if the share is a user share, else null.
type: number
type:
description: >
The type of this share. One of the following values:
GROUP or USER.
type: string
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
ccMe:
description: >
Indicates whether to send a copy of the email to the
sharer of the sheet. You can specify this attribute
in a request, but it is never present in a response.
type: boolean
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
email:
description: User's primary email address for user shares; null
for group shares.
type: string
message:
description: >
The message included in the body of the email that is
optionally sent to the recipient. You can specify
this attribute in a request, but it is never present in a response.
type: string
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
name:
description: If a user share and user is also a contact, the user's
full name. If a group share, the group's name.
type: string
scope:
description: >
The scope of this share. One of the following values:
* **ITEM**: an item-level share (that is, the specific object
to which the share applies is shared with
the user or group).
* **WORKSPACE**: a workspace-level share (that is, the workspace
that contains the object to which the
share applies is shared with the user or group).
type: string
subject:
description: >
The subject of the email that is optionally sent to
notify the recipient. You can specify this attribute
in a request, but it is never present in a response.
type: string
- type: array
items:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: >
Result object containing either a single Share object or an array of
Share objects, corresponding
to what was specified in the request. All shares have scope=ITEM.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
- type: array
items:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
'400':
description: >
If called with a single Share object, and that user or group share
already exists, error code 1025 is returned.
If called with an array of Share objects, and one or more user or group
shares in the array already exist,
they are ignored and omitted from the response.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/responses/400/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/reports/{reportId}/shares?sendEmail=true'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{\"email\": \"jane.doe@smartsheet.com\"\
, \"accessLevel\": \"EDITOR\"}]'\n"
- lang: C#
source: "// Specify share (to one user as Editor)\nShare[] shareSpecification\
\ = new Share[] { new Share\n {\n Email = \"jane.doe@smartsheet.com\"\
,\n AccessLevel = AccessLevel.EDITOR\n }\n};\n\n// Share report\nIList\
\ addressList = smartsheet.ReportResources.ShareResources.ShareTo(\n 665829219035012,\
\ // long reportId\n shareSpecification,\n true \
\ // Nullable sendEmail\n);\n"
- lang: Java
source: "// Specify share (to one user as Editor)\nShare shareSpecification\
\ = new Share()\n .setEmail(\"jane.doe@smartsheet.com\")\n \
\ .setAccessLevel(AccessLevel.EDITOR);\n\n// Share report\nList\
\ addressList = smartsheet.reportResources().shareResources().shareTo(\n\
\ 665829219035012L, // long reportId\n Arrays.asList(shareSpecification),\n\
\ true // Boolean sendEmail\n );\n"
- lang: JavaScript
source: "// Specify share (to one user as Editor)\nvar share = [\n\t{\n\t\t\
\"email\": \"jane.doe@smartsheet.com\",\n\t\t\"accessLevel\": \"EDITOR\"\
\n\t}\n];\n\n// Set options\nvar options = {\n reportId: 665829219035012,\n\
\ body: share\n };\n\n// Share report\nsmartsheet.reports.share(options)\n\
\ .then(function(addressList) {\n console.log(addressList);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Reports.share_report(\n 665829219035012,\
\ # report_id\n smartsheet.models.Share({\n 'access_level': 'EDITOR',\n\
\ 'email': 'jane.doe@smartsheet.com'\n })\n)\n"
- lang: Ruby
source: "body = {\n email: 'jane.doe@smartsheet.com',\n access_level: 'EDITOR',\n\
\ subject: 'This report has been shared with you!',\n message: 'This Smartsheet\
\ report is ready for your inspection.'\n}\n\nresponse = smartsheet.reports.share.create(\n\
\ report_id: 665829219035012,\n body: body\n)\n"
get:
summary: List Report Shares
description: >
Gets a list of all users and groups to whom the specified Report is
shared, and their access level.
This operation supports query string parameters for pagination of results.
operationId: list-report-shares
tags:
- sharing
- reports
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- name: sharingInclude
in: query
description: When applicable for the specific object this parameter defines
the scope of the share. Possible values are ITEM or WORKSPACE. ITEM is an
item-level share (that is, the specific object to which the share applies
is shared with the user or group). WORKSPACE is a workspace-level share
(that is, the workspace that contains the object to which the share applies
is shared with the user or group).
required: false
schema:
type: string
enum:
- ITEM
- WORKSPACE
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: >
IndexResult object containing an array of Share objects. By default,
this operation returns only
item-level shares (scope=ITEM). Use the sharingInclude parameter to request
that workspace-level shares
(scope=WORKSPACE) also be returned.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/responses/400/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/reports/{reportId}/shares \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult shares = smartsheet.ReportResources.ShareResources.ListShares(\n\
\ 665829219035012, // long reportId\n null, //\
\ PaginationParameters\n null // ShareScope shareScope\n\
);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult shares = smartsheet.reportResources().shareResources().listShares(\n\
\ 665829219035012L, // long reportId\n null, \
\ // PaginationParameters\n true \
\ // Boolean includeWorkspaceShares\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n reportId: 665829219035012\n};\n\
\n// List report shares\nsmartsheet.reports.listShares(options)\n .then(function(shareList)\
\ {\n console.log(shareList);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Reports.list_shares(include_all=True)\n\
shares = response.result\n\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Reports.list_shares(\n\
\ page_size=10,\n page=1)\npages = response.total_pages\nshares = response.result\n"
- lang: Ruby
source: "response = smartsheet.reports.share.list(\n report_id: 665829219035012\n\
)\nshares = response[:data]\n"
/reports/{reportId}/shares/{shareId}:
parameters:
- $ref: '#/paths/~1reports~1%7BreportId%7D/parameters/2'
- name: shareId
in: path
schema:
type: string
required: true
description: Share Id.
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Report Share.
description: Gets the share specified in the URL.
operationId: share-report-get
tags:
- sharing
- reports
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: Returns Share object.
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Share share = smartsheet.ReportResources.ShareResources.GetShare(\n\
\ 6932724448552836, // long reportId\n \"AQAISF82FOeE\"\
\ // string shareId\n);\n"
- lang: Java
source: "Share share = smartsheet.reportResources().shareResources().getShare(\n\
\ 665829219035012L, // long reportId\n \"AAAQSF82F1eE\"\
\ // string shareId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n reportId: 6932724448552836,\n\
\ shareId: \"AQAISF82FOeE\"\n};\n\n// Get report share\nsmartsheet.reports.getShare(options)\n\
\ .then(function(share) {\n console.log(share);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "share = smartsheet_client.Reports.get_share(\n 6932724448552836,\
\ # report_id\n 'AAAQSF82F1eE') # share_id\n"
- lang: Ruby
source: "share = smartsheet.reports.share.get(\n report_id: 6932724448552836,\n\
\ share_id: 'AAABbMomFOeE'\n)\n"
delete:
summary: Delete Report Share
description: Deletes the share specified in the URL.
operationId: delete-report-share
tags:
- sharing
- reports
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
responses:
'200':
description: Returns Result object.
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares~1%7BshareId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.ReportResources.ShareResources.DeleteShare(\n 665829219035012,\
\ // long reportId\n \"AAAQSF82F1eE\" // string\
\ shareId\n);\n"
- lang: Java
source: "smartsheet.reportResources().shareResources().deleteShare(\n \
\ 665829219035012L, // long reportId\n \"AAAQSF82F1eE\"\
\ // string shareId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n reportId: 665829219035012,\n \
\ shareId: \"AAAQSF82F1eE\"\n};\n\n// Delete report share\nsmartsheet.reports.deleteShare(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Reports.delete_share(\n 665829219035012, \
\ # report_id\n 'AAAQSF82F1eE') # share_id\n"
- lang: Ruby
source: "smartsheet.reports.share.delete(\n report_id: 665829219035012,\n\
\ share_id: 'AAAQSF82F1eE'\n)\n"
put:
summary: Update Report Share.
description: Updates the access level of a user or group for the specified report.
operationId: update-report-share
tags:
- sharing
- reports
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares~1%7BshareId%7D/get/responses/200/content/application~1json/schema'
responses:
'200':
description: Result object containing the modified Share object
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares~1%7BshareId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: object
items:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares~1%7BshareId%7D/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares~1%7BshareId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/reports/{reportId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{\"accessLevel\": \"VIEWER\"}'\n"
- lang: C#
source: "// Set the access level to Viewer\nShare shareSpecification = new\
\ Share\n{\n Id = \"AAAFeF82FOeE\",\n AccessLevel = AccessLevel.VIEWER\n\
};\n\n// Update report share\nShare updatedShare = smartsheet.ReportResources.ShareResources.UpdateShare(\n\
\ 665829219035012, // long reportId\n shareSpecification\n\
);\n"
- lang: Java
source: "// Set the access level to Viewer\nShare shareSpecification = new\
\ Share();\n shareSpecification.setAccessLevel(AccessLevel.VIEWER)\n\
\ .setId(\"AAAFeF82FOeE\"); // string shareId\n\n// Update report\
\ share\nShare updatedShare = smartsheet.reportResources().shareResources().updateShare(\n\
\ 665829219035012L, // long reportId\n shareSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Set the access level to Viewer\nvar share = {\"accessLevel\":\
\ \"VIEWER\"};\n\n// Set options\nvar options = {\n reportId: 665829219035012,\n\
\ shareId: \"AAAFeF82FOeE\",\n body: share\n };\n\n// Update report share\n\
smartsheet.reports.updateShare(options)\n .then(function(updatedShare)\
\ {\n console.log(updatedShare);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_share = smartsheet_client.Reports.update_share(\n 665829219035012,\
\ # report_id\n 'AAAFeF82FOeE', # share_id\n smartsheet.models.Share({\n\
\ 'access_level': 'VIEWER'\n })\n)\n"
- lang: Ruby
source: "body = {\n access_level: 'VIEWER'\n}\n\nresponse = smartsheet.reports.share.update(\n\
\ report_id: 665829219035012,\n share_id: 'AAABbMomFOeE',\n body: body\n\
)\n"
/search:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Search Everything
description: Searches all sheets that the user can access, for the specified
text.
tags:
- search
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: list-search
parameters:
- name: query
in: query
required: true
description: Text with which to perform the search. Enclose in double-quotes
for an exact search.
schema:
type: string
responses:
'200':
description: IndexResult object containing an array of Search objects.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
type: object
properties:
results:
description: Array of SearchResultItem objects.
type: array
items:
$ref: '#/components/schemas/SearchResult/properties/results/items'
totalCount:
description: Total number of search results.
type: number
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/search?query=stuff' \\\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Set search criteria\nstring query = \"stuff\";\n\n// Search everything\n\
SearchResult results = smartsheet.SearchResources.Search(query);\n"
- lang: Java
source: "// Set search criteria\nString query = \"stuff\";\n\n// Search everything\n\
SearchResult results = smartsheet.searchResources().search(query);\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n query: \"stuff\"\n};\n\n// Search\
\ everything\nsmartsheet.search.searchAll(options)\n .then(function(results)\
\ {\n console.log(results);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "# Set search criteria\nquery = 'stuff'\n\n# Search everything\nresult\
\ = smartsheet_client.Search.search(query)\n# result is a smartsheet.models.SearchResult\
\ object\n"
- lang: Ruby
source: "results = smartsheet.search.search_all(\n query: 'stuff'\n)\n"
/search/sheets/{sheetId}:
parameters:
- name: sheetId
in: path
schema:
type: number
required: true
description: Sheet Id of the sheet being accessed.
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Search Sheet
description: Gets a list of the user's search results in a sheet based on query.
The list contains an abbreviated row object for each search result in a sheet.
*Note* Newly created or recently updated data may not be immediately discoverable
via search.
tags:
- search
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: list-search-sheet
parameters:
- $ref: '#/paths/~1search/get/parameters/0'
responses:
'200':
description: IndexResult object containing an array of Search objects in
a sheet
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/SearchResult/properties/results/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/search/sheets/{sheetId}?query=stuff'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Set search criteria\nstring query = \"stuff\";\n\n// Search sheet\n\
SearchResult results = smartsheet.SearchResources.SearchSheet(\n 9283173393803140,\
\ // sheetId\n query // string\n);\n"
- lang: Java
source: "// Set search criteria\nstring query = \"stuff\";\n\n// Search sheet\n\
SearchResult results = smartsheet.searchResources().searchSheet(\n \
\ 9283173393803140L, // long sheetId\n query\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 1888207043356548,\n \
\ queryParameters: {\n query: \"stuff\"\n }\n};\n\n// Search sheet\n\
smartsheet.search.searchSheet(options)\n .then(function (data) {\n console.log(data);\n\
\ })\n .catch(function (error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Set search criteria\nquery = 'stuff'\n\n# Search sheet\nresponse\
\ = smartsheet_client.Search.search_sheet(\n 9283173393803140, #\
\ sheet_id\n query)\n# response is a smartsheet.models.SearchResult object\n"
- lang: Ruby
source: "response = smartsheet.search.search_sheet(\n query: 'stuff',\n \
\ sheet_id: 9283173393803140\n)\n"
/serverinfo:
get:
summary: Gets application constants.
description: Gets application constants.
operationId: serverinfo-get
tags:
- serverInfo
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
formats:
$ref: '#/components/schemas/ServerInfo/properties/formats'
supportedLocales:
description: Array of strings representing all Smartsheet-supported
locales.
type: array
items:
type: string
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/serverinfo\n"
- lang: C#
source: "ServerInfo serverInfo = smartsheet.ServerInfoResources.GetServerInfo();\n"
- lang: Java
source: "ServerInfo serverInfo = smartsheet.serverInfoResources().getServerInfo();\n"
- lang: JavaScript
source: "smartsheet.server.getInfo()\n .then(function(serverInfo) {\n \
\ console.log(serverInfo);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "info = smartsheet_client.Server.server_info()\n"
- lang: Ruby
source: "info = smartsheet.server_info.get\n"
/sheets:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Sheets
description: >
Gets a list of all sheets that the user has access to. The list contains
an abbreviated Sheet object for each sheet.
operationId: list-sheets
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of optional elements to include in the
response:
* **sheetVersion** - current version number of each sheet, should not be
combined with pagination
* **source** - the Source object for any sheet that was created from another
sheet, if any
schema:
type: string
enum:
- sheetVersion
- source
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/1'
- $ref: '#/paths/~1contacts/get/parameters/2'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
type: array
items:
type: object
properties:
id:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/id'
accessLevel:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/accessLevel'
createdAt:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/modifiedAt'
name:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/name'
permalink:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/permalink'
version:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/version'
source:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/source'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Sample 1: Omit 'include' parameter and pagination parameters\n\
PaginatedResult sheets = smartsheet.SheetResources.ListSheets(\n\
\ null, // IEnumerable includes\n null,\
\ // PaginationParameters\n null // Nullable\
\ modifiedSince\n);\n\n// Sample 2: Specify 'include' parameter with value\
\ of \"SOURCE\", and 'includeAll' parameter with value of 'true'\nPaginatedResult\
\ sheets = smartsheet.SheetResources.ListSheets(\n new SheetInclusion[]\
\ { SheetInclusion.SOURCE },\n new PaginationParameters(\n true, \
\ // includeAll\n null, // int pageSize\n null) \
\ // int page\n);\n"
- lang: Java
source: "// Sample 1: Omit 'include' parameter and pagination parameters\n\
PagedResult sheets = smartsheet.sheetResources().listSheets(\n \
\ null, // EnumSet includes\n null,\
\ // PaginationParameters\n null // Date modifiedSince\n\
\ );\n\n// Sample 2: Specify pagination parameter 'includeAll'\n\
PaginationParameters parameters = new PaginationParameters()\n .setIncludeAll(true);\n\
\n// Specify 'include' parameter with value of \"SOURCE\", and 'includeAll'\
\ parameter with value of 'true'\nPagedResult sheets = smartsheet.sheetResources().listSheets(EnumSet.of(SourceInclusion.SOURCE),\
\ parameters, modifiedSince);\n"
- lang: JavaScript
source: "smartsheet.sheets.listSheets()\n\t.then(function(sheetList) {\n\t\
\tconsole.log(sheetList);\n\t})\n\t.catch(function(error) {\n\t\tconsole.log(error);\n\
\t});\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.list_sheets(include_all=True)\n\
sheets = response.data\n"
- lang: Ruby
source: "# Sample 1: Omit 'includeAll' parameter\nresponse = smartsheet.sheets.list\n\
sheets = response[:data]\n\n# Sample 2: Specify 'includeAll' with a value\
\ of 'true'\nresponse = smartsheet.sheets.list(params: {includeAll:true\
\ })\nsheets = response\n"
post:
summary: Create Sheet in "Sheets" Folder
description: >
Creates a sheet from scratch or from the specified template in the
user's Sheets folder (Home).
For subfolders, use Create Sheet in Folder.
operationId: create-sheet-in-sheets-folder
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/parameters/1'
requestBody:
description: Sheet to create.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/requestBody/content/application~1json/schema/oneOf/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/requestBody/content/application~1json/schema/oneOf/1'
responses:
'200':
description: Result object containing a Sheet object for newly created sheet,
corresponding to what was specified in the request.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "// Sample 1: Create sheet\ncurl https://api.smartsheet.com/2.0/sheets\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"name\":\"newsheet\",\"columns\"\
:[{\"title\":\"Favorite\",\"type\":\"CHECKBOX\",\"symbol\":\"STAR\"}, {\"\
title\":\"Primary Column\", \"primary\":true,\"type\":\"TEXT_NUMBER\"}]}'\n\
\n\n// Sample 2: Create sheet from template\ncurl 'https://api.smartsheet.com/2.0/sheets?include=data,attachments,discussions'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"name\":\"newsheet\", \"fromId\"\
: templateId}'\n"
- lang: C#
source: "// Sample 1: Create sheet\n// Specify properties of the first column\n\
Column columnA = new Column\n{\n Title = \"Favorite\",\n Primary = false,\n\
\ Type = ColumnType.CHECKBOX,\n Symbol = Symbol.STAR\n};\n\n// Specify\
\ properties of the second column\nColumn columnB = new Column\n{\n Title\
\ = \"Primary Column\",\n Primary = true,\n Type = ColumnType.TEXT_NUMBER\n\
};\n\n// Create sheet in \"Sheets\" folder (specifying the 2 columns to\
\ include in the sheet)\nSheet newSheet = smartsheet.SheetResources.CreateSheet(new\
\ Sheet\n{\n Name = \"newsheet\",\n Columns = new Column[] { columnA,\
\ columnB }\n}\n);\n\n// Sample 2: Create sheet from template\n// Specify\
\ name for the sheet and Id of the template\nSheet sheetSpecification =\
\ new Sheet\n{\n Name = \"new sheet title\",\n FromId = 7679398137620356\
\ // template Id\n};\n\n// Option 1: Omit 'include' parameter\nSheet\
\ newSheet = smartsheet.SheetResources.CreateSheetFromTemplate(\n sheetSpecification,\n\
\ null // IEnumerable include\n\
);\n\n// Option 2: Include ATTACHMENTS, DATA, and DISCUSSIONS\nSheet newSheet\
\ = smartsheet.SheetResources.CreateSheetFromTemplate(\n sheetSpecification,\n\
\ new TemplateInclusion[] {\n TemplateInclusion.ATTACHMENTS,\n TemplateInclusion.DATA,\n\
\ TemplateInclusion.DISCUSSIONS }\n);\n\n"
- lang: Java
source: "// Sample 1: Create sheet\n// Specify properties of the first column\n\
Column columnA = new Column()\n .setTitle(\"Favorite\")\n \
\ .setType(ColumnType.CHECKBOX)\n .setSymbol(Symbol.STAR);\n\n//\
\ Specify properties of the second column\nColumn columnB = new Column()\n\
\ .setTitle(\"Primary Column\")\n .setType(ColumnType.TEXT_NUMBER)\n\
\ .setPrimary(true);\n\n// Create sheet in \"Sheets\" folder (specifying\
\ the 2 columns to include in the sheet)\nSheet newSheet = new Sheet();\n\
\ newSheet.setName(\"newsheet\");\n newSheet.setColumns(Arrays.asList(columnA,\
\ columnB));\n\nsmartsheet.sheetResources().createSheet(newSheet);\n\n//\
\ Sample 2: Create sheet from template\n// Specify name for the sheet and\
\ Id of the template\n Sheet sheet = new Sheet();\n sheet.setFromId(7679398137620356L);\
\ // long templateId\n sheet.setName(\"newsheet\");\n\n// Option\
\ 1: Omit 'include' parameter\n Sheet results = smartsheet.sheetResources().createSheetFromTemplate(sheet,\n\
\ null // EnumSet\
\ includes\n );\n\n// Option 2: Include ATTACHMENTS, DATA, and DISCUSSIONS\n\
\ Sheet results = smartsheet.sheetResources().createSheetFromTemplate(\n\
\ sheet,\n EnumSet.of(\n SheetTemplateInclusion.ATTACHMENTS,\n\
\ SheetTemplateInclusion.DATA,\n SheetTemplateInclusion.DISCUSSIONS)\n\
\ );\n\n"
- lang: JavaScript
source: "// Sample 1: Create sheet\n// Specify sheet properties\nvar sheet\
\ = {\n \"name\": \"newsheet\",\n \"columns\": [\n {\n \"title\"\
: \"Favorite\",\n \"type\": \"CHECKBOX\",\n \"symbol\": \"STAR\"\
\n },\n {\n \"title\": \"Primary Column\",\n \"primary\"\
: true,\n \"type\": \"TEXT_NUMBER\"\n }\n ]\n};\n\n// Set options\n\
var options = {\n body: sheet\n};\n\n// Create sheet in \"Sheets\" folder\n\
smartsheet.sheets.createSheet(options)\n\t.then(function(newSheet) {\n\t\
\tconsole.log(newSheet);\n\t})\n\t.catch(function(error) {\n\t\tconsole.log(error);\n\
\t});\n\n// Sample 2: Create sheet from template\n// Specify the directive\n\
var sheet = {\n \"fromId\": 7679398137620356,\n \"name\": \"newsheet\"\
\n };\n\n// Set options\nvar options = {\n body: sheet\n};\n\n// Create\
\ sheet from template\nsmartsheet.sheets.createSheetFromExisting(options)\n\
\ .then(function(newSheet) {\n console.log(newSheet);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n\n"
label: Node.js
- lang: Python
source: "# Sample 1: Create sheet\nsheet_spec = smartsheet.models.Sheet({\n\
\ 'name': 'newsheet',\n 'columns': [{\n 'title': 'Favorite',\n \
\ 'type': 'CHECKBOX',\n 'symbol': 'STAR'\n }, {\n 'title':\
\ 'Primary Column',\n 'primary': True,\n 'type': 'TEXT_NUMBER'\n\
\ }\n ]\n})\nresponse = smartsheet_client.Home.create_sheet(sheet_spec)\n\
new_sheet = response.result\n\n# Sample 2: Create sheet from template\n\
response = smartsheet_client.Home.create_sheet_from_template(\n smartsheet.models.Sheet({\n\
\ 'name': 'newsheet',\n 'from_id': 7679398137620356 # template_id\n\
\ })\n)\nnew_sheet = response.result\n\n"
- lang: Ruby
source: "# Sample 1: Create sheet\nbody = {\n name: 'newsheet',\n columns:\
\ [\n {\n title: 'Favorite',\n type: 'CHECKBOX',\n symbol:\
\ 'STAR',\n width: 10\n },\n {\n title: 'Primary Column',\n\
\ type: 'TEXT_NUMBER',\n primary: true\n }\n ]\n}\n\nresponse\
\ = smartsheet.sheets.create(\n body: body\n)\nnew_sheet = response[:result]\n\
\n# Sample 2: Create sheet from template\nbody = {\n name: 'newsheet',\n\
\ from_id: 7679398137620356\n}\n\nresponse = smartsheet.sheets.create_from_template(\n\
\ body: body\n)\nnew_sheet = response[:result]\n\n"
/sheets/import:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Import Sheet from CSV / XLSX
description: >
Imports CSV or XLSX data into a new sheet in the top-level "Sheets"
folder.
Note the following:
* Both sheetName and the file name must use ASCII characters.
* The source data must be basic text. To include rich formula data, import
and create a sheet first, and then use Update Rows. To work with images, see
Cell Images.
* XLS is not supported. You must use XLSX.
* Hierarchical relationships between rows in an external file won't import.
operationId: import-sheet-into-sheets-folder
tags:
- import
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
parameters:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/1'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/2'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/3'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/4'
requestBody:
description: Binary content for the CSV / XLSX file.
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: Result object containing a Sheet object for imported sheet.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/responses/200/content/application~1json/schema/allOf/1/properties/result'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/import?sheetName=MarketingProgressReport&headerRowIndex=0&primaryColumnIndex=0\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Disposition:\
\ attachment\" \\\n-H \"Content-Type: text/csv\" \\\n-X POST \\\n--data-binary\
\ @ProgressReport.csv\n"
- lang: C#
source: "Sheet sheet = smartsheet.SheetResources.ImportXlsSheet(\n \"D:/ProgressReport.xlsx\"\
,\n null, // sheetName defaults to file name unless specified\n\
\ 0, // headerRowIndex\n null // primaryColumnIndex\n\
);\n"
- lang: Java
source: "Sheet sheet = smartsheet.sheetResources().importXlsx(\n \"\
D:/ProgressReport.xlsx\",\n \"MarketingProgressReport\",\n \
\ 0, // headerRowIndex\n 0 // primaryColumnIndex\n \
\ );\n"
- lang: JavaScript
source: "// Sample 1: Import sheet from CSV\n// Set options\nvar options =\
\ {\n queryParameters: {\n sheetName: 'MarketingProgressReport'\n\
\ },\n path: \"D:/ProgressReport.csv\"\n};\n\n// Import CSV as sheet\n\
smartsheet.sheets.importCsvSheet(options)\n .then(function(attachment)\
\ {\n console.log(attachment);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n\n// Sample 2: Import sheet from XLSX\n\
// Set options\nvar options = {\n queryParameters: {\n sheetName: 'MarketingProgressReport'\n\
\ },\n path: \"D:/ProgressReport.xlsx\"\n};\n\n// Import XLSX as sheet\n\
smartsheet.sheets.importXlsxSheet(options)\n .then(function(attachment)\
\ {\n console.log(attachment);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "imported_sheet = smartsheet_client.Sheets.import_xlsx_sheet(\n 'D:/ProgressReport.xlsx',\n\
\ 'MarketingProgressReport', # sheet_name\n header_row_index=0\n)\n"
- lang: Ruby
source: "# Sample 1: Import from file\nsmartsheet.sheets.import_from_file(\n\
\ file: ProgressReport.csv,\n file_type: :csv,\n file_length: ProgressReport.size,\n\
\ params: {sheetName: 'MarketingProgressReport', headerRowIndex: 0, primaryColumnIndex:\
\ 0})\n\n# Sample 2: Import from file path\nsmartsheet.sheets.import_from_file_path(\n\
\ path: 'D:\\ProgressReport.csv',\n file_type: :csv,\n params: {sheetName:\
\ 'MarketingProgressReport', headerRowIndex: 0, primaryColumnIndex: 0})\n"
/sheets/{sheetId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
get:
summary: Get Sheet
description: Gets a sheet in the format specified, based on the sheet Id.
operationId: getSheet
parameters:
- $ref: '#/paths/~1reports~1%7BreportId%7D/parameters/1'
- name: include
in: query
required: false
description: >
A comma-separated list of optional elements to include in the
response:
* **attachments** - includes the metadata for sheet-level and row-level
attachments. To include discussion attachments, both attachments and discussions
must be present in the include list.
* **columnType** -includes columnType attribute in the row's cells indicating
the type of the column the cell resides in.
* **crossSheetReferences** - includes the cross-sheet references
* **discussions** - includes sheet-level and row-level discussions. To
include discussion attachments, both attachments and discussions must be
present in the include list.
* **filters** - includes filteredOut attribute indicating if the row should
be displayed or hidden according to the sheet's filters.
* **filterDefinitions** - includes type of filter, operators used, and
criteria
* **format** - includes column, row, cell, and summary fields formatting.
* **ganttConfig** - includes Gantt chart details.
* **objectValue** - when used in combination with a level query parameter,
includes the email addresses for multi-contact data.
* **ownerInfo** - includes the workspace and the owner's email address
and user Id.
* **rowPermalink** - includes permalink attribute that represents a direct
link to the row in the Smartsheet application.
* **source** - adds the Source object indicating which report, sheet Sight
(aka dashboard), or template the sheet was created from, if any.
* **writerInfo** - includes createdBy and modifiedBy attributes on the
row or summary fields, indicating the row or summary field's creator, and
last modifier.
schema:
type: string
enum:
- attachments
- columnType
- crossSheetReferences
- discussions
- filters
- filterDefinitions
- format
- ganttConfig
- objectValue
- ownerInfo
- rowPermalink
- source
- writerInfo
- name: exclude
in: query
required: false
description: >
A comma-separated list of optional elements to not include in the
response:
* **filteredOutRows** - excludes filtered out rows from response payload
if a sheet filter is applied; includes total number of filtered rows
* **linkInFromCellDetails** - excludes the following attributes from the
**cell.linkInFromCell** object: columnId, rowId, status
* **linksOutToCellsDetails** - excludes the following attributes from
the **cell.linksOutToCells** array elements: columnId, rowId, status
* **nonexistentCells** - excludes cells that have never contained any
data
schema:
type: string
enum:
- filteredOutRows
- linkInFromCellDetails
- linksOutToCellsDetails
- nonexistentCells
- name: columnIds
in: query
required: false
description: >
A comma-separated list of column ids. The response contains only the
specified columns in the "columns" array, and individual rows'
"cells" array only contains cells in the specified columns.
schema:
type: string
- name: filterId
in: query
required: false
description: >
Overrides the existing include={filters} parameter if both are
supplied. Applies the given filter (if accessible by the calling
user) and marks the affected rows as "filteredOut": true.
schema:
type: string
- name: ifVersionAfter
in: query
required: false
description: >
If version specified is still the current sheet version, then
returns an abbreviated Sheet object with only the sheet version
property. Otherwise, if the sheet has been modified, returns the
complete Sheet object. Intended to allow clients with a cached copy
to make sure they have the latest version.
schema:
type: integer
- name: level
in: query
required: false
description: 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).
schema:
type: integer
default: 1
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/3'
- name: paperSize
in: query
required: false
description: applies to PDF format only
schema:
type: string
enum:
- LETTER
- LEGAL
- WIDE
- ARCHD
- A4
- A3
- A2
- A1
- A0
default: LETTER
- name: rowIds
in: query
required: false
description: >
A comma-separated list of row Ids on which to filter the rows
included in the result.
schema:
type: string
- name: rowNumbers
in: query
required: false
description: >
A comma-separated list of row numbers on which to filter the rows
included in the result. Non-existent row numbers are ignored.
schema:
type: string
- name: rowsModifiedSince
in: query
required: false
description: Filter to return only rows that have been modified since the
date/time provided. Date should be in ISO-8601 format.
example: 2020-01-30T13:25:32-07:00
schema:
$ref: '#/components/schemas/Attachment/properties/createdAt'
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: The Sheet that was loaded.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Folder/properties/sheets/items'
- type: object
properties:
version:
description: A number that represents the current sheet version.
type: number
application/pdf:
schema:
type: string
format: binary
description: The Sheet in PDF format.
application/vnd.ms-excel:
schema:
type: string
format: binary
description: The Sheet in Excel format.
text/csv:
schema:
type: string
format: binary
description: The Sheet in CSV format.
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "// Sample 1: Get sheet\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}?level=2&include=objectValue\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n\n// Sample\
\ 2: Get sheet as Excel\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Accept:\
\ application/vnd.ms-excel\" \\\n-o output.xlsx\n\n// Sample 3: Get sheet\
\ as PDF\ncurl 'https://api.smartsheet.com/2.0/sheets/{sheetId}?paperSize=A1'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Accept:\
\ application/pdf\"\n-o output.pdf\n\n// Sample 4: Get sheet as CSV\ncurl\
\ https://api.smartsheet.com/2.0/sheets/{sheetId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Accept: text/csv\" \\\n-o\
\ output.csv\n\n\n"
- lang: C#
source: "// Sample 1: Get sheet\n// Omit all parameters\nSheet sheet = smartsheet.SheetResources.GetSheet(\n\
\ 4583173393803140, // sheetId\n null, \
\ // IEnumerable includes\n null, \
\ // IEnumerable excludes\n null, \
\ // IEnumerable rowIds\n null, \
\ // IEnumerable rowNumbers\n null, // IEnumerable\
\ columnIds\n null, // Nullable pageSize\n\
\ null // Nullable page\n);\n\n// Sample 2:\
\ Get sheet as Excel\nsmartsheet.SheetResources.GetSheetAsExcel(\n 4583173393803140,\
\ // sheetId\n outputStream\n);\n\n// Sample 3: Get sheet as\
\ PDF\nsmartsheet.SheetResources.GetSheetAsPDF(\n 4583173393803140, \
\ // sheetId\n outputStream,\n PaperSize.A1\n);\n\n// Sample\
\ 4: Get sheet as CSV\nsmartsheet.SheetResources.GetSheetAsCSV(\n 4583173393803140,\
\ // sheetId\n outputStream\n);\n\n\n\n"
- lang: Java
source: "// Sample 1: Get sheet\n// Omit all parameters\nSheet sheet = smartsheet.sheetResources().getSheet(\n\
\ 4583173393803140L, // long sheetId\n null, \
\ // EnumSet includes\n null, \
\ // EnumSet excludes\n null, \
\ // Set rowIds\n null, // Set\
\ rowNumbers\n null, // Set columnIds\n \
\ null, // Integer pageSize\n null \
\ // Integer page\n );\n\n// Sample 2: Get sheet as\
\ Excel\nsmartsheet.sheetResources().getSheetAsExcel(\n 4583173393803140L,\
\ // long sheetId\n outputStream\n );\n\n// Sample 3:\
\ Get sheet as PDF\nsmartsheet.sheetResources().getSheetAsPDF(\n \
\ 4583173393803140L, // long sheetId\n outputStream,\n \
\ PaperSize.A1\n );\n\n// Sample 4: Get sheet as CSV\nsmartsheet.sheetResources().getSheetAsCSV(\n\
\ 4583173393803140L, // long sheetId\n outputStream\n\
\ );\n\n"
- lang: JavaScript
source: "// Sample 1: Get sheet\n// Set options\nvar options = {\n id: 4583173393803140\
\ // Id of Sheet\n};\n\n// Get sheet\nsmartsheet.sheets.getSheet(options)\n\
\t.then(function(sheetInfo) {\n\t\tconsole.log(sheetInfo);\n\t})\n\t.catch(function(error)\
\ {\n\t\tconsole.log(error);\n\t});\n\n// Sample 2: Get sheet as Excel\n\
var fs = require(\"fs\")\n\n// Set options\nvar options = {\n id: 169681224483716\
\ // Id of Sheet\n};\n\n// Get sheet\nsmartsheet.sheets.getSheetAsExcel(options)\n\
\ .then(function(fileContents) {\n // Write sheet to file\n fs.writeFile('output.xlsx',\
\ fileContents, 'binary', (err) => {\n if (err) throw err;\n console.log('The\
\ sheet has been saved!');\n });\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n\n// Sample 3: Get sheet as PDF\nvar fs\
\ = require(\"fs\")\n\n// Set options\nvar options = {\n id: 169681224483716\
\ // Id of Sheet\n};\n\n// Get sheet\nsmartsheet.sheets.getSheetAsPDF(options)\n\
\ .then(function(fileContents) {\n // Write sheet to file\n fs.writeFile('output.pdf',\
\ fileContents, 'binary', (err) => {\n if (err) throw err;\n console.log('The\
\ sheet has been saved!');\n });\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n\n// Sample 4: Get sheet as CSV\nvar fs\
\ = require(\"fs\")\n\n// Set options\nvar options = {\n id: 4583173393803140\
\ // Id of Sheet\n};\n\n// Get sheet\nsmartsheet.sheets.getSheetAsCSV(options)\n\
\ .then(function(fileContents) {\n // Write sheet to file\n fs.writeFile('output.csv',\
\ fileContents, (err) => {\n if (err) throw err;\n console.log('The\
\ sheet has been saved!');\n });\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n\n\n\n"
label: Node.js
- lang: Python
source: "# Sample 1: Get sheet\nsheet = smartsheet_client.Sheets.get_sheet(\n\
\ 4583173393803140) # sheet_id\n\n# Sample 2: Get sheet as Excel\n\
smartsheet_client.Sheets.get_sheet_as_excel(\n 1531988831168388, \
\ # sheet_id\n download_directory_path)\n\n# Sample 3: Get sheet as\
\ PDF\nsmartsheet_client.Sheets.get_sheet_as_pdf(\n 1531988831168388, \
\ # sheet_id\n download_directory_path,\n 'A1') \
\ # paperSize\n\n# Sample 4: Get sheet as CSV\nsmartsheet_client.Sheets.get_sheet_as_csv(\n\
\ 1531988831168388, # sheet_id\n download_directory_path)\n"
- lang: Ruby
source: "# Sample 1: Get sheet\nsheet = smartsheet.sheets.get(\n sheet_id:\
\ 4583173393803140\n)\n\n# Sample 2: Get sheet as Excel\nfile_contents =\
\ smartsheet.sheets.get_as_excel(\n sheet_id: 1531988831168388\n)\n\nFile.open('output.xlsx',\
\ 'w') {|f| f.write(file_contents)}\n\n# Sample 3: Get sheet as PDF\nfile_contents\
\ = smartsheet.sheets.get_as_pdf(\n sheet_id: 1531988831168388\n)\n\nFile.open('output.pdf',\
\ 'w') {|f| f.write(file_contents)}\n\n# Sample 4: Get sheet as CSV\nfile_contents\
\ = smartsheet.sheets.get_as_csv(\n sheet_id: 1531988831168388\n)\n\nFile.open('output.csv',\
\ 'w') {|f| f.write(file_contents)}\n\n\n"
delete:
summary: Delete Sheet
description: Deletes the sheet specified in the URL.
operationId: deleteSheet
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- DELETE_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.SheetResources.DeleteSheet(\n 1531988831168388 \
\ // sheetId\n);\n"
- lang: Java
source: "smartsheet.sheetResources().deleteSheet(\n 1531988831168388L\
\ // long sheetId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n id: 1531988831168388 // Id of\
\ Sheet\n};\n\n// Delete sheet\nsmartsheet.sheets.deleteSheet(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.delete_sheet(\n 1531988831168388) \
\ # sheet_id\n"
- lang: Ruby
source: "smartsheet.sheets.delete(sheet_id: 1531988831168388)\n"
put:
summary: Update Sheet
description: >-
Updates the sheet specified in the URL.
To modify sheet contents, see [Add Rows](../../tag/rows#operation/rows-addToSheet),
[Update Rows](../../tag/rows#operation/update-rows), [Add Columns](../../tag/columns#operation/columns-addToSheet),
and [Update Column](../../tag/columns#operation/column-updateColumn).
This operation can be used to update an individual user's sheet settings.
If the request body contains only the **userSettings** attribute, this operation
may be performed even if the user only has read-only access to the sheet (for
example, the user has viewer permissions or the sheet is read-only).
operationId: updateSheet
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
requestBody:
description: >
[Sheet object](../../tag/sheetsObjects#section/Sheet-Object) limited
to the following attributes:
* **name** (optional).
* **projectSettings** (optional): [ProjectSettings object](../../tag/sheetsObjects#section/ProjectSettings-Object),
containing at least one of the **projectSettings** attributes, for updating
this sheet's project settings and dependencies.
* **userSettings** (optional): [SheetUserSettings object](../../tag/sheetsObjects#section/SheetUserSettings-Object)
for updating these user's settings for the sheet.
NOTE:
* Attributes not specified in **projectSettings** are not updated.
* If **projectSettings.nonWorkingDays** is specified as an empty array,
all non-working days are removed from the project sheet.
content:
application/json:
schema:
type: object
properties:
name:
description: Sheet name.
type: string
projectSettings:
$ref: '#/components/schemas/Sheet/properties/projectSettings'
userSettings:
$ref: '#/components/schemas/Sheet/properties/userSettings'
responses:
'200':
description: Returns [Result object](../../tag/commonObjects#section/Result-Object)
containing a [Sheet object](../../tag/sheetsObjects#section/Sheet-Object)
for the updated sheet.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D/get/responses/200/content/application~1json/schema/oneOf/0'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X PUT \\\n-d '{\"name\":\"New Sheet Name\",\n \"userSettings\":\
\ {\"criticalPathEnabled\": true},\n \"projectSettings\":{\n \"workingDays\"\
: [\"MONDAY\", \"TUESDAY\", \"WEDNESDAY\"],\n \"nonWorkingDays\": [\"\
2018-01-01\"],\n \"lengthOfDay\": 6\n } \\\n}'\n"
- lang: C#
source: "// Specify updated sheet properties\nSheet sheetSpecification = new\
\ Sheet\n{\n Id = 4583173393803140,\n Name = \"New Sheet Name\",\n UserSettings\
\ = new SheetUserSettings{CriticalPathEnabled = true}\n};\n\n// Update sheet\n\
Sheet updatedSheet = smartsheet.SheetResources.UpdateSheet(sheetSpecification);\n"
- lang: Java
source: "// Specify updated sheet properties\nSheet sheetSpecification = new\
\ Sheet();\nsheetSpecification.setUserSettings(new SheetUserSettings().setCriticalPathEnabled(true))\n\
\ .setName(\"New Sheet Name\")\n .setId(7960873114331012L);\n\
\n// Update sheet\nSheet updatedSheet = smartsheet.sheetResources().updateSheet(sheetSpecification);\n"
- lang: JavaScript
source: "// Specify updated sheet properties\nvar sheet = {\n \"name\": \"\
New Sheet Name\",\n \"userSettings\": {\n \"criticalPathEnabled\": true,\n\
\ }\n};\n\n// Set options\nvar options = {\n id: 7960873114331012, //\
\ Id of Sheet\n body: sheet\n };\n\n// Update sheet\nsmartsheet.sheets.updateSheet(options)\n\
\ .then(function(updatedSheet) {\n console.log(updatedSheet);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_sheet = smartsheet_client.Sheets.update_sheet(\n 4583173393803140,\
\ # sheet_id\n smartsheet.models.Sheet({\n 'name': 'New Sheet\
\ Name',\n 'user_settings': smartsheet.models.SheetUserSettings({\n \
\ 'critical_path_enabled': True\n })\n })\n)\n"
- lang: Ruby
source: "body = {\n name: 'New Sheet Name',\n user_settings: {\n critical_path_enabled:\
\ true,\n display_summary_tasks: false\n },\n project_settings: {\n\
\ working_days: ['MONDAY', 'TUESDAY', 'WEDNESDAY'],\n non_working_days:\
\ ['2018-01-01'],\n length_of_day: 6\n }\n}\n\nresponse = smartsheet.sheets.update(\n\
\ sheet_id: 4583173393803140,\n body: body\n)\nupdated_sheet = response\n"
/sheets/{sheetId}/attachments:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Attachments
description: >
Gets a list of all attachments that are on the sheet, including sheet,
row, and discussion-level attachments.
operationId: attachments-listOnSheet
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of attachments
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult attachments\
\ = smartsheet.SheetResources.AttachmentResources.ListAttachments(\n 9283173393803140,\
\ // sheetId\n null // PaginationParameters\n\
);\n"
- lang: Java
source: "// Omit pagination\nPagedResult attachments = smartsheet.sheetResources().attachmentResources().listAttachments(\n\
\ 9283173393803140L, // long sheetId\n null\
\ // PaginationParameters\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140\n};\n\
\n// List attachments\nsmartsheet.sheets.listAttachments(options)\n .then(function(attachmentsList)\
\ {\n console.log(attachmentsList);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List All\nresponse = smartsheet_client.Attachments.list_all_attachments(\n\
\ 9283173393803140, # sheet_id\n include_all=True)\nattachments\
\ = response.data\n\n# Sample 2: Paginate the list of attachments\nresponse\
\ = smartsheet_client.Attachments.list_all_attachments(\n 9283173393803140,\
\ # sheet_id\n page_size=10,\n page=1)\npages = response.total_pages\n\
attachments = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.attachments.list(\n sheet_id: 9283173393803140\n\
)\nattachments = response[:data]\n"
post:
summary: Attach File or URL to Sheet
description: |
Attaches a file to the sheet. The URL can be any of the following:
* Normal URL (attachmentType "LINK")
* Box.com URL (attachmentType "BOX_COM")
* Dropbox URL (attachmentType "DROPBOX")
* Egnyte URL (attachmentType "EGNYTE")
* Evernote URL (attachmentType "EVERNOTE")
* Google Drive URL (attachmentType "GOOGLE_DRIVE")
* OneDrive URL (attachmentType "ONEDRIVE")
For multipart uploads please use "multipart/form-data" content type.
operationId: attachments-attachToSheet
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
multipart/form-data:
schema:
type: object
properties:
name:
type: string
filename:
type: string
format: binary
application/json:
schema:
type: object
properties:
attachmentSubType:
description: Attachment sub type. * type is for EGNYTE values and
the rest are GOOGLE_DRIVE values.
type: string
enum:
- DOCUMENT
- DRAWING
- FOLDER*
- PDF
- PRESENTATION
- SPREADSHEET
attachmentType:
description: Attachment type. * types are not supported for Smartsheet.gov
accounts.
type: string
enum:
- BOX_COM
- DROPBOX*
- EGNYTE*
- EVERNOTE*
- FILE
- GOOGLE_DRIVE
- LINK
- ONEDRIVE
description:
type: string
name:
type: string
url:
type: string
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1attachments/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/msword\" \\\n-H 'Content-Disposition: attachment; filename=\"\
ProgressReport.docx\"' \\\n-H \"Content-Length: FILE_SIZE\" \\\n-X POST\
\ \\\n--data-binary @ProgressReport.docx\n"
- lang: C#
source: "Attachment attachment = smartsheet.SheetResources.AttachmentResources.AttachFile(\n\
\ 9283173393803140, // sheetId\n filePath,\n \"application/msword\"\
\n);\n"
- lang: Java
source: "// Specify file to be attached\nFile file = new File(\"/Users/jdoe/Documents/ProgressReport.docx\"\
);\n\n// Attach file to sheet\n Attachment attachment = smartsheet.sheetResources().attachmentResources().attachFile(\n\
\ 9283173393803140L, // long sheetId\n file,\n \
\ \"application/msword\"\n );\n"
- lang: JavaScript
source: "// Enable FileStream\nvar fs = require(\"fs\")\n\n// Set options\n\
var options = {\n sheetId: 1694401624483716,\n fileSize: 20765,\n fileName:\
\ \"ProgressReport.docx\",\n fileStream: fs.createReadStream(\"/Users/jdoe/Documents/ProgressReport.docx\"\
)\n};\n\n// Attach file to sheet\nsmartsheet.sheets.addFileAttachment(options)\n\
\ .then(function(attachment) {\n console.log(attachment);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_attachment = smartsheet_client.Attachments.attach_file_to_sheet(\n\
\ 9283173393803140, # sheet_id\n ('ProgressReport.docx',\n open('/path/to/ProgressReport.docx',\
\ 'rb'),\n 'application/msword')\n)\n"
- lang: Ruby
source: "# Sample 1: Attach file from path\nresponse = smartsheet.sheets.attachments.attach_file_from_path(\n\
\ sheet_id: 4583173393803140,\n path: '/Users/jdoe/Documents/ProgressReport.docx'\n\
)\nnew_attachment = response[:result]\n\n# Sample 2: Attach file\nfilename\
\ = '/Users/jdoe/Documents/ProgressReport.docx'\nfile = File.open(filename)\n\
file_length = File.size(filename)\n\nresponse = smartsheet.sheets.attachments.attach_file(\n\
\ sheet_id: 4583173393803140,\n file: file,\n filename: filename,\n \
\ file_length: file_length\n)\nnew_attachment = response[:result]\n"
/sheets/{sheetId}/attachments/{attachmentId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: attachmentId
in: path
required: true
description: ID of the attachment
schema:
type: string
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Attachment
description: >
Fetches a temporary URL that allows you to download an attachment. The
urlExpiresInMillis attribute tells you how long the URL is valid.
operationId: attachments-get
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Comment/properties/attachments/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Attachment attachment = smartsheet.SheetResources.AttachmentResources.GetAttachment(\n\
\ 9283173393803140, // sheetId\n 4583173393803140 \
\ // attachmentId\n);\n"
- lang: Java
source: "Attachment attachment = smartsheet.sheetResources().attachmentResources().getAttachment(\n\
\ 9283173393803140L, // long sheetId\n 4583173393803140L\
\ // long attachmentId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140,\n \
\ attachmentId: 4583173393803140\n};\n\n// Get attachment\nsmartsheet.sheets.getAttachment(options)\n\
\ .then(function(attachment) {\n console.log(attachment);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "attachment = smartsheet_client.Attachments.get_attachment(\n 9283173393803140,\
\ # sheet_id\n 4583173393803140) # attachment_id\n"
- lang: Ruby
source: "attachment = smartsheet.sheets.attachments.get(\n sheet_id: 9283173393803140,\n\
\ attachment_id: 4583173393803140\n)\n"
delete:
summary: Delete Attachment
description: |
Deletes the attachment specified in the URL.
operationId: attachments-delete
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.SheetResources.AttachmentResources.DeleteAttachment(\n\
\ 9283173393803140, // sheetId\n 7169782752536452 \
\ // attachmentId\n);\n"
- lang: Java
source: "smartsheet.sheetResources().attachmentResources().deleteAttachment(\n\
\ 9283173393803140L, // long sheetId\n 7169782752536452L\
\ // sheetAttachmentId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ attachmentId: 7169782752536452,\n};\n\n// Delete attachment\nsmartsheet.sheets.deleteAttachment(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Attachments.delete_attachment(\n 9283173393803140,\
\ # sheet_id\n 7169782752536452) # attachment_id\n"
- lang: Ruby
source: "smartsheet.sheets.attachments.delete(\n sheet_id: 4583173393803140,\n\
\ attachment_id: 7169782752536452\n)\n"
/sheets/{sheetId}/attachments/{attachmentId}/versions:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1attachments~1%7BattachmentId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Versions
description: >
Gets a list of all versions of the given attachmentId in order from
newest to oldest.
operationId: attachments-versionList
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of attachments
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult attachments\
\ = smartsheet.SheetResources.AttachmentResources.VersioningResources.ListVersions(\n\
\ 2252168947361668, // sheetId\n 5510069950408580, \
\ // attachmentId\n null // PaginationParameters\n\
);\n"
- lang: Java
source: "// Omit pagination\nPagedResult attachments = smartsheet.sheetResources().attachmentResources().versioningResources().listAllVersions(\n\
\ 2252168947361668L, // long sheetId\n 5510069950408580L,\
\ // long attachmentId\n null // PaginationParameters\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ attachmentId: 5510069950408580\n};\n\n// List versions of the attachment\n\
smartsheet.sheets.listAttachmentVersions(options)\n .then(function(versionList)\
\ {\n console.log(versionList);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Attachments.list_attachment_versions(\n\
\ 2252168947361668, # sheet_id\n 5510069950408580, # attachment_id\n\
\ include_all=True)\nversions = response.data\n\n# Sample 2: Paginate the\
\ list\nresponse = smartsheet_client.Attachments.list_attachment_versions(\n\
\ 2252168947361668, # sheet_id\n 5510069950408580, # attachment_id\n\
\ page_size=5,\n page=1)\npages = response.total_pages\nversions = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.attachments.list_versions(\n sheet_id:\
\ 4583173393803140,\n attachment_id: 5510069950408580\n)\nversions = response[:data]\n"
post:
summary: Attach New version
description: >
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.
operationId: attachments-versionUpload
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
multipart/form-data:
schema:
type: object
properties:
name:
type: string
filename:
type: string
format: binary
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1attachments~1%7BattachmentId%7D~1versions/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/msword\" \\\n-H 'Content-Disposition: attachment; filename=\"\
ProgressReport.docx\"' \\\n-H \"Content-Length: FILE_SIZE\" \\\n-X POST\
\ \\\n--data-binary @ProgressReport.docx\n"
- lang: C#
source: "Attachment attachment = smartsheet.SheetResources.AttachmentResources.VersioningResources.AttachNewVersion(\n\
\ 9283173393803140, // sheetId\n 0123456789123456, \
\ // attachmentId\n filePath,\n \"application/msword\"\n);\n"
- lang: Java
source: "// Specify the new file to be attached\nFile file = new File(\"/Users/jdoe/Documents/ProgressReport.docx\"\
);\n\n// Attach new version of the file\n Attachment attachment =\
\ smartsheet.sheetResources().attachmentResources().versioningResources().attachNewVersion(\n\
\ 9283173393803140L, // long sheetId\n 0123456789123456L,\
\ // long attachmentId\n file,\n \"application/msword\"\
\n );\n"
- lang: JavaScript
source: "// Enable FileStream\nvar fs = require(\"fs\")\n\n// Set options\n\
var options = {\n sheetId: 9283173393803140,\n attachmentId: 0123456789123456,\n\
\ fileSize: 17291,\n fileName: \"ProgressReport.docx\",\n fileStream:\
\ fs.createReadStream(\"/Users/jdoe/Documents/ProgressReport.docx\")\n};\n\
\n// Attach new version\nsmartsheet.sheets.attachNewVersion(options)\n \
\ .then(function(updatedAttachment) {\n console.log(updatedAttachment);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Attachments.attach_new_version(\n 9283173393803140,\
\ # sheet_id\n 0123456789123456, # attachment_id\n ('ProgressReport.docx',\n\
\ open('/path/to/ProgressReport.docx', 'rb'),\n 'application/msword')\n\
)\n\nupdated_attachment = response.result\n"
- lang: Ruby
source: "# Sample 1: Attach new version from path\nresponse = smartsheet.sheets.attachments.attach_new_version_from_path(\n\
\ sheet_id: 9283173393803140,\n attachment_id: 0123456789123456,\n path:\
\ '/Users/jdoe/Documents/ProgressReport.docx'\n)\nupdated_attachment = response[:result]\n\
\n# Sample 2: Attach new version\nfilename = '/Users/jdoe/Documents/ProgressReport.docx'\n\
file = File.open(filename)\nfile_length = File.size(filename)\n\nresponse\
\ = smartsheet.sheets.attachments.attach_new_version(\n sheet_id: 9283173393803140,\n\
\ attachment_id: 0123456789123456,\n file: file,\n filename: filename,\n\
\ file_length: file_length\n)\nupdated_attachment = response[:result]\n"
delete:
summary: Delete All Versions
description: >
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.
operationId: attachments-versionsDelete
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1attachments~1%7BattachmentId%7D~1versions/post/responses/200/content/application~1json/schema/allOf/0'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/attachments/{attachmentId}/versions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.SheetResources.AttachmentResources.VersioningResources.DeleteAllVersions(\n\
\ 9283173393803140, // sheetId\n 0123456789123456 \
\ // attachmentId\n);\n"
- lang: Java
source: "smartsheet.sheetResources().attachmentResources().versioningResources().deleteAllVersions(\n\
\ 9283173393803140L, // long sheetId\n 0123456789123456L\
\ // long attachmentId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ attachmentId: 5510069950408580\n};\n\n// Delete all versions of the attachment\n\
smartsheet.sheets.deleteAllAttachmentVersions(options)\n .then(function(results)\
\ {\n console.log(results);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Attachments.delete_attachment_versions(\n 9283173393803140,\
\ # sheet_id\n 0123456789123456) # attachment_id\n"
- lang: Ruby
source: "smartsheet.sheets.attachments.delete_all_versions(\n sheet_id: 9283173393803140,\n\
\ attachment_id: 0123456789123456\n)\n"
/sheets/{sheetId}/automationrules:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
operationId: automationrules-list
summary: List All Automation Rules
description: >
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.
tags:
- automationRules
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: The list of AutomationRule objects
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of Automation Rules
type: array
items:
type: object
properties:
id:
description: AutomationRule Id.
type: number
action:
description: AutomationAction object containing information
for this rule, such as type, recipients, and frequency.
allOf:
- $ref: '#/components/schemas/AutomationRule/properties/action/allOf/0'
createdAt:
description: A timestamp of when the rule was originally
added.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: >
`User` object containing `name` and `email` of
the creator of this rule.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
disabledReason:
description: >
Machine-readable reason a rule is disabled:
* `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.
type: string
enum:
- APPROVAL_COLUMN_MISSING
- APPROVAL_COLUMN_WRONG_TYPE
- AUTOMATION_NOT_ENABLED_FOR_ORG
- COLUMN_MISSING
- COLUMN_TYPE_INCOMPATIBLE
- NO_POTENTIAL_RECIPIENTS
- NO_VALID_SELECTED_COLUMNS
disabledReasonText:
description: Descriptive reason a rule is disabled.
type: string
enabled:
description: If true, indicates that the rule is active.
type: boolean
modifiedAt:
description: The datetime for when the change was made
to the rule.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedBy:
description: >
`User` object containing the `name` and `email`
of the user that made the change.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
name:
description: Rule name as shown in the UI.
type: string
userCanModify:
description: If true, indicates that the current user
can modify the rule.
type: boolean
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "PaginatedResult AutomationRules = smartsheet.SheetResources.AutomationRuleResources.ListAutomationRules(\n\
\ 9283173393803140, // sheetId\n null // PaginationParameters\n\
);"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140\n};\n\
\n// List automation rules\nsmartsheet.sheets.listAutomationRules(options)\n\
\ .then(function(automationRulesList) {\n console.log(automationRulesList);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.list_automation_rules(\n 9283173393803140,\
\ # sheet_id\n include_all=True)\nautomation_rules = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.automation_rules.list(\n sheet_id:\
\ 9283173393803140\n)\nrules = response[:data]"
/sheets/{sheetId}/automationrules/{automationRuleId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: automationRuleId
in: path
required: true
description: The Id of an Automation Rule
schema:
type: string
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get an Automation Rule
description: |
Returns the specified automation rule, including any action values.
operationId: automationrule-get
tags:
- automationRules
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: AutomationRule object
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1automationrules/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId}\
\ \\\n -H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "AutomationRule automationRule = smartsheet.SheetResources.GetAutomationRule(\n\
\ 9283173393803140, // sheetId\n 789994550205316 \
\ // automationRuleId\n);"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140,\n \
\ automationRuleId: 789994550205316\n};\n\n// Get automation rule\nsmartsheet.sheets.getAutomationRule(options)\n\
\ .then(function(automationRule) {\n console.log(automationRule);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "automation_rule = smartsheet_client.Sheets.get_automation_rule(\n\
\ 4478580756375428, # sheet_id\n 4220838007334788) # automation_rule_id\n"
- lang: Ruby
source: "rule = smartsheet.sheets.automation_rules.get(\n sheet_id: 9283173393803140,\n\
\ automation_rule_id: 789994550205316\n)"
put:
summary: Update an Automation Rule
description: >
Updates an existing automation rule.
When sending an AutomationRule, you must always specify **action.type** and
it must match the existing rule type.
operationId: automationrule-update
tags:
- automationRules
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1automationrules~1%7BautomationRuleId%7D/get/responses/200/content/application~1json/schema/allOf/0'
responses:
'200':
description: Result object containing the updated AutomationRule object
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1automationrules~1%7BautomationRuleId%7D/get/responses/200/content/application~1json/schema/allOf/0'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X PUT\
\ \\\n-d '{\n \"action\": {\n \"type\": \"APPROVAL_REQUEST_ACTION\"\
,\n \"recipients\": [{\n \"email\": \"jane.roe@smartsheet.com\"\
\n }],\n \"frequency\": \"WEEKLY\"\n }\n}'"
- lang: C#
source: "// Set recipient\nRecipient recipient = new Recipient\n{\n Email\
\ = \"jane.roe@smartsheet.com\"\n};\n\n// Specify the changes\nAutomationRule\
\ autoRule = new AutomationRule\n{\n Id = 789994550205316,\n Action =\
\ new AutomationAction\n {\n Recipients = new[] { recipient },\n \
\ Type = AutomationActionType.NOTIFICATION_ACTION,\n Frequency = AutomationActionFrequency.WEEKLY\n\
\ }\n};\n\n// Update the automation rule\nAutomationRule automationRule\
\ = smartsheet.SheetResources.UpdateAutomationRule(\n 4583173393803140,\
\ // sheetId\n autoRule\n);"
- lang: JavaScript
source: "// Specify the changes\nvar body = {\n \"name\": \"Approval Request\"\
,\n \"action\": {\n \"type\": \"APPROVAL_REQUEST_ACTION\",\n \"recipients\"\
: [\n {\n \"email\": \"jane.roe@smartsheet.com\"\n }\n\
\ ],\n \"frequency\": \"WEEKLY\",\n \"includeAllColumns\": true,\n\
\ \"includeAttachments\": true,\n \"includeDiscussions\": true,\n\
\ \"notifyAllSharedUsers\": false\n }\n};\n\n// Set options\nvar options\
\ = {\n sheetId: 4583173393803140,\n automationRuleId: 789994550205316,\n\
\ body: body\n};\n\n// Update the automation rule\nsmartsheet.sheets.updateAutomationRule(options)\n\
\ .then(function(updatedAutomationRule) {\n console.log(updatedAutomationRule);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "automation_spec = smartsheet.models.AutomationRule({\n 'enabled':\
\ False, # Disable Automation Rule\n 'name': 'New Name',\
\ # Change Name of Automation Rule\n 'action': {\n 'type':\
\ 'NOTIFICATION_ACTION' # Action/Type must always be included\n }\n})\n\
\nresponse = smartsheet_client.Sheets.update_automation_rule(\n 4478580756375428,\
\ # sheet_id\n 4220838007334788, # automation_rule_id\n\
\ automation_spec)\n\nupdated_automation = response.result\n"
- lang: Ruby
source: "smartsheet.sheets.automation_rules.update(\n sheet_id: 4583173393803140,\n\
\ automation_rule_id: 789994550205316,\n body: {\n name: 'Approval\
\ Request',\n enabled: true,\n action: {\n type: 'APPROVAL_REQUEST_ACTION',\n\
\ recipients: [\n {\n email: 'jane.roe@smartsheet.com'\n\
\ }\n ],\n frequency: 'WEEKLY',\n include_all_columns:\
\ true,\n include_attachments: true,\n include_discussions: true,\n\
\ notify_all_shared_users: false\n }\n})"
delete:
summary: Delete an Automation Rule
description: |
Deletes an automation rule.
operationId: automationrule-delete
tags:
- automationRules
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
responses:
'200':
description: Result object
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1automationrules~1%7BautomationRuleId%7D/put/responses/200/content/application~1json/schema/allOf/0'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/automationrules/{automationRuleId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE"
- lang: C#
source: "AutomationRule automationRule = smartsheet.SheetResources.AutomationRuleResources.DeleteAutomationRule(\n\
\ 9283173393803140, // sheetId\n 789004550205316 \
\ // automationRuleId\n);"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140,\n \
\ automationRuleId: 789004550205316\n};\n\n// Delete automation rule\nsmartsheet.sheets.deleteAutomationRule(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n \
\ .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.delete_automation_rule(\n 4478580756375428,\
\ # sheet_id\n 4220838007334788) # automation_rule_id\n"
- lang: Ruby
source: "smartsheet.sheets.automation_rules.delete(\n sheet_id: 9283173393803140,\n\
\ automation_rule_id: 789004550205316\n)"
/sheets/{sheetId}/columns:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Columns
description: Gets a list of all columns belonging to the sheet specified in
the URL.
operationId: columns-listOnSheet
parameters:
- name: level
in: query
required: false
description: specifies whether multi-contact data is returned in a backwards-compatible,
text format (level=0, default) or as multi-contact data (level=1).
schema:
type: integer
default: 1
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
tags:
- columns
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: Returns [IndexResult object]() containing an array of [Column
objects]().
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: number
description: Column Id.
index:
type: number
description: Column index or position. This number is
zero-based.
symbol:
type: string
description: When applicable for **CHECKBOX** or **PICKLIST**
column types. See [Symbol Columns](../../tag/columnsRelated#section/Column-Types/Symbol-Columns).
title:
type: string
description: Column title.
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
description: See [Column Types](../../tag/columnsRelated#section/Column-Types)
validation:
type: boolean
description: Indicates whether validation has been enabled
for the column (value = **true**).
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit 'include' parameter and pagination parameters\nPaginatedResult\
\ columns = smartsheet.SheetResources.ColumnResources.ListColumns(\n 9283173393803140,\
\ // sheetId\n null, // IEnumerable\
\ include\n null, // PaginationParameters\n \
\ 2 // int compatibilityLevel\n);\n"
- lang: Java
source: "// Omit 'include' parameter and pagination parameters\nPagedResult\
\ columns = smartsheet.sheetResources().columnResources().listColumns(\n\
\ 9283173393803140L, // long sheetId\n null,\
\ // EnumSet includes\n\
\ null // PaginationParameters\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140\n};\n\
\n// List columns\nsmartsheet.sheets.getColumns(options)\n .then(function(columnList)\
\ {\n console.log(columnList);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.get_columns(\n 9283173393803140,\
\ # sheet_id\n include_all=True)\ncolumns = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.columns.list(\n sheet_id: 9283173393803140\n\
)\ncolumns = response[:data]\n"
post:
summary: Add Columns
description: Inserts one or more columns into the sheet specified in the URL.This
operation can be performed using a [simple upload](../../tag/attachmentsDescription#section/Post-an-Attachment/Simple-Uploads)
or a [multipart upload](../../tag/attachmentsDescription#section/Post-an-Attachment/Multipart-Uploads).
For more information, see [Post an Attachment](../../tag/attachmentsDescription#section/Post-an-Attachment).
operationId: columns-addToSheet
tags:
- columns
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
description: |
A [Column object]() that contains the following attributes
* **title**
* **type**
* **formula** (optional)
* **index** (zero-based)
* **autoNumberFormat** (optional)
* **description** (optional)
* **locked**(optional)
* **options** (optional)
* **symbol** (optional)
* **systemColumnType** (optional)
* **validation** (optional)
* **width** (optional)
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: Column title.
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
formula:
type: string
description: The formula for a column, if set, for instance **=data@row**.
hidden:
type: boolean
description: Indicates whether the column is hidden.
index:
type: number
description: Column index or position. This number is zero-based.
autoNumberFormat:
$ref: '#/components/schemas/Column/properties/autoNumberFormat'
contactOptions:
$ref: '#/components/schemas/Column/properties/contactOptions/items'
description:
type: string
description: Column description.
format:
type: string
description: The format descriptor (see [Formatting](../#section/API-Basics/Formatting)).
Only returned if the **include** query string parameter contains
**format** and this column has a non-default format applied to
it.
locked:
type: boolean
description: 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:
type: boolean
description: 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:
type: array
items:
type: string
description: Array of the options available for the column.
symbol:
type: string
description: When applicable for **CHECKBOX** or **PICKLIST** column
types. See [Symbol Columns](../../tag/columnsRelated#section/Column-Types/Symbol-Columns).
systemColumnType:
type: string
enum:
- AUTO_NUMBER
- CREATED_BY
- CREATED_DATE
- MODIFIED_BY
- MODIFIED_DATE
description: See [System Columns](../../tag/columnsRelated#section/Column-Types)
validation:
type: boolean
description: Indicates whether validation has been enabled for the
column (value = **true**)
version:
type: number
description: >
Read only. The level of the column type. Each element in the
array is set to one of the following values:
* **0**: TEXT_NUMBER, CONTACT_LIST, or PICKLIST
* **1**: MULTI_CONTACT_LIST
* **2**: MULTI_PICKLIST
See [Versioning and Changes](#section/API-Basics/Versioning-and-Changes).
width:
type: number
description: Display width of the column in pixels.
responses:
'200':
description: Returns [Result object](../../tag/commonObjects#section/Result-Object)
containing the newly created columns -- either a single [Column object](../../tag/columnsObjects#section/Column-Object)
or an array of Column objects, corresponding to what was specified in
the request.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: array
items:
type: object
properties:
id:
type: number
description: Column Id.
index:
type: number
description: Column index or position. This number is
zero-based.
title:
type: string
description: Column title.
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
description: See [Column Types](../../tag/columnsRelated#section/Column-Types)
options:
type: array
items:
type: string
description: Array of the options available for the column.
validation:
type: boolean
description: Indicates whether validation has been enabled
for the column (value = **true**).
width:
type: number
description: Display width of the column in pixels.
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{\"title\": \"New Multi-Picklist\
\ Column 1\", \"type\": \"MULTI_PICKLIST\", \"options\": [\"First\", \"\
Second\", \"Third\"], \"index\": 4} , {\"title\":\"New Date Column\", \"\
type\":\"DATE\", \"formula\": \"=data@row\", \"validation\":\"true\", \"\
index\":4},]'\n-d '[{\"index\": 6, \"title\": \"Dropdown Multi Select\"\
, \"type\": \"MULTI_PICKLIST\", \"options\": [\"Template\", \"Blog\",\t\"\
Newsletter\",\t\"Email\", \"Press Release\", \"Advertisement\"],\t\"validation\"\
: false, \"width\": 150}]'\n"
- lang: C#
source: "// Create a column\nColumn columnA = new Column\n{\n Title = \"\
This is a new multi-picklist column\",\n Index = 0,\n Type = ColumnType.MULTI_PICKLIST,\n\
\ Options = new string[] { \"Cat\", \"Rat\", \"Bat\" }\n};\n\n// Create\
\ another column\nColumn columnB = new Column\n{\n Title = \"New Date Column\"\
,\n Index = 4,\n Type = ColumnType.DATE\n};\n\n// Add columns to the sheet\n\
IList addedColumns = smartsheet.SheetResources.ColumnResources.AddColumns(\n\
\ 2252168947361668, // sheet Id\n new Column[] { columnA, columnB }\n\
);\n"
- lang: Java
source: "// Create columns\nColumn column1 = new Column()\n .setTitle(\"\
New Multi-Picklist Column 1\")\n .setType(ColumnType.MULTI_PICKLIST)\n\
\ .setIndex(4)\n .setOptions(Arrays.asList(\"First\", \"Second\"\
, \"Third\"));\n\n Column column2 = new Column()\n .setTitle(\"\
New Date Column\")\n .setType(ColumnType.DATE)\n .setFormula(\"\
=data@row\")\n .setValidation(true)\n .setIndex(4);\n\n//\
\ Add columns to the sheet\n List newColumns = smartsheet.sheetResources().columnResources().addColumns(\n\
\ 2252168947361668L, // long sheetId\n Arrays.asList(column1,\
\ column2)\n );\n"
- lang: JavaScript
source: "// Specify new columns\nvar column = [\n {\n \"title\": \"New\
\ Picklist Column 1\",\n \"type\": \"PICKLIST\",\n \"options\": [\n\
\ \"First\",\n \"Second\",\n \"Third\"\n ],\n \"index\"\
: 4\n },\n {\n \"title\": \"New Date Column\",\n \"type\": \"DATE\"\
,\n \"formula\": \"=data@row\",\n \"validation\": true,\n \"index\"\
: 4\n }\n];\n\n// Set options\nvar options = {\n sheetId: 2252168947361668,\n\
\ body: column\n };\n\n// Add columns to the sheet\nsmartsheet.sheets.addColumn(options)\n\
\ .then(function(newColumns) {\n console.log(newColumns);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Create the columns\ncolumn1 = smartsheet.models.Column({\n 'title':\
\ 'New Picklist Column 1',\n 'type': 'PICKLIST',\n 'options': [\n 'First',\n\
\ 'Second',\n 'Third'\n ],\n 'index': 4\n})\n\ncolumn2 = smartsheet.models.Column({\n\
\ 'title': 'New Date Column',\n 'type': 'DATE',\n 'formula': '=data@row',\n\
\ 'validation': 'True',\n 'index': 4\n})\n\n# Add columns to the sheet\n\
new_columns = smartsheet_client.Sheets.add_columns(\n 2252168947361668,\
\ # sheet_id\n [column1, column2])\n"
- lang: Ruby
source: "# Define options\nbody = {\n title: 'New Picklist Column 1',\n \
\ type: 'PICKLIST',\n options: [\n 'First',\n 'Second',\n 'Third'\n\
\ ],\n index: 4\n},\n{\n title: \"New Date Column\",\n type: 'DATE',\n\
\ formula: 'data@row',\n validation: true,\n index: 4\n}\n\n# Add the\
\ column\nnew_columns = smartsheet.sheets.columns.add(\n sheet_id: 2252168947361668,\n\
\ body: body\n)\n"
/sheets/{sheetId}/columns/{columnId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: columnId
in: path
schema:
type: number
required: true
description: Column Id in the sheet being accessed.
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Column
description: Gets the column specified in the URL.
operationId: column-get
parameters:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D/get/parameters/6'
tags:
- columns
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1columns/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Sample 1: Omit 'include' parameter\nColumn column = smartsheet.SheetResources.ColumnResources.GetColumn(\n\
\ 9283173393803140, // sheetId\n 7960873114331012, \
\ // columnId\n null // IEnumerable\
\ includes\n);\n\n// Sample 2: Specify 'include' parameter with value of\
\ \"FILTERS\"\nColumn column = smartsheet.SheetResources.ColumnResources.GetColumn(\n\
\ 9283173393803140, // sheetId\n 7960873114331012, \
\ // columnId\n new ColumnInclusion[] { ColumnInclusion.FILTERS\
\ }\n);\n"
- lang: Java
source: "// Sample 1: Omit 'include' parameter\nColumn column = smartsheet.sheetResources().columnResources().getColumn(\n\
\ 9283173393803140L, // long sheetId\n 7960873114331012L,\
\ // long columnId\n null // EnumSet\
\ includes\n );\n\n// Sample 2: Specify 'include' parameter with\
\ value of \"FILTERS\"\n Column column = smartsheet.sheetResources().columnResources().getColumn(\n\
\ 9283173393803140L, // long sheetId\n 7960873114331012L,\
\ // long columnId\n EnumSet.of(ColumnInclusion.FILTERS)\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140,\n \
\ columnId: 7960873114331012\n};\n\n// Get column\nsmartsheet.sheets.getColumns(options)\n\
\ .then(function(column) {\n console.log(column);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "column = smartsheet_client.Sheets.get_column(\n 9283173393803140,\
\ # sheet_id\n 7960873114331012) # column_id\n"
- lang: Ruby
source: "column = smartsheet.sheets.columns.get(\n sheet_id: 9283173393803140,\n\
\ column_id: 7960873114331012\n)\n"
delete:
summary: Delete Column
description: Deletes the column specified in the URL.
operationId: column-delete
tags:
- columns
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.SheetResources.ColumnResources.DeleteColumn(\n 9283173393803140,\
\ // sheetId\n 0123456789012345 // columnId\n\
);\n"
- lang: Java
source: "smartsheet.sheetResources().columnResources().deleteColumn(\n \
\ 9283173393803140L, // long sheetId\n 0123456789012345L\
\ // long columnId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140,\n \
\ columnId: 0123456789012345\n};\n\n// Delete column\nsmartsheet.sheets.deleteColumn(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.delete_column(\n 9283173393803140, \
\ # sheet_id\n 0123456789012345) # column_id\n"
- lang: Ruby
source: "smartsheet.sheets.columns.delete(\n sheet_id: 9283173393803140,\n\
\ column_id: 0123456789012345\n)\n"
put:
summary: Update Column
description: >
Updates properties of the column, moves the column, or renames the
column.
**NOTE:**
* You cannot change the type of a Primary column.
* While dependencies are enabled on a sheet, you can't change the type of
any special calendar/Gantt columns.
* If the column type is changed, all cells in the column are converted to
the new column type and column validation is cleared.
* Type is optional when moving or renaming, but required when changing type
or dropdown values.
operationId: column-updateColumn
tags:
- columns
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
requestBody:
description: >
A [Column object]() that contains the following attributes:
* **index**
* **autoNumberFormat** (optional)
* **contactOptions** (optional) -- must have set column type to CONTACT_LIST
* **description** (optional)
* **format** (optional)
* **formula** (optional)
* **hidden**(optional)
* **locked** (optional)
* **options** (optional)
* **symbol** (optional)
* **systemColumnType** (optional)
* **title** (optional)
* **type** (optional)
* **validation** (optional)
* **width** (optional)
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1columns/post/requestBody/content/application~1json/schema'
responses:
'200':
description: Returns [Result object](../../tag/commonObjects#section/Result-Object)
containing the [Column object](../../tag/columnsObjects#section/Column-Object)
that was modified.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1columns~1%7BcolumnId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: object
properties:
id:
type: number
description: Column Id.
index:
type: number
description: Column index or position. This number is zero-based.
options:
type: array
items:
type: string
description: Array of the options available for the column.
title:
type: string
description: Column title.
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
description: See [Column Types](../../tag/columnsRelated#section/Column-Types)
validation:
type: boolean
description: Indicates whether validation has been enabled
for the column (value = **true**).
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X PUT\
\ \\\n-d '{\"title\": \"New multi-select dropdown column\", \"index\": 0,\
\ \"type\": \"MULTI_PICKLIST\", \"options\": [\"One\", \"Two\"]}'\n"
- lang: C#
source: "// Specify column properties\nColumn columnSpecification = new Column\n\
{\n Id = 5005385858869124,\n Title = \"First Column\",\n Index = 0,\n\
\ Type = ColumnType.PICKLIST,\n Options = new string[] { \"One\", \"Two\"\
}\n};\n\n// Update column\nColumn updatedColumn = smartsheet.SheetResources.ColumnResources.UpdateColumn(\n\
\ 2252168947361668, // sheetId\n columnSpecification\n);\n"
- lang: Java
source: "// Specify column properties\nColumn columnSpecification = new Column(5005385858869124L)\n\
\ .setTitle(\"First Column\")\n .setIndex(0)\n .setType(ColumnType.PICKLIST)\n\
\ .setOptions(Arrays.asList(\"One\", \"Two\"));\n\n// Update column\n\
\ Column updatedColumn = smartsheet.sheetResources().columnResources().updateColumn(\n\
\ 2252168947361668L, // sheetId\n columnSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Specify column properties\nvar column = {\n \"index\": 0,\n \
\ \"title\": \"First Column\",\n \"type\": \"PICKLIST\",\n \"options\"\
: [\"One\", \"Two\"]\n};\n\n// Set options\nvar options = {\n sheetId:\
\ 2252168947361668,\n columnId: 5005385858869124,\n body: column\n };\n\
\n// Update column\nsmartsheet.sheets.updateColumn(options)\n .then(function(updatedColumn)\
\ {\n console.log(updatedColumn);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Specify column properties\ncolumn_spec = smartsheet.models.Column({\n\
\ 'title': 'First Column',\n 'type': 'PICKLIST',\n 'options': [\"One\"\
, \"Two\"],\n 'index': 0\n})\n\n# Update column\nresponse = smartsheet_client.Sheets.update_column(\n\
\ 2252168947361668, # sheet_id\n 5005385858869124, # column_id\n\
\ column_spec)\n\nupdated_column = response.result\n"
- lang: Ruby
source: "# Specify column properties\nbody = {\n title: 'First Column',\n\
\ type: 'PICKLIST',\n options: [\n 'One',\n 'Two'\n ]\n}\n\n# Update\
\ column\nresponse = smartsheet.sheets.columns.update(\n sheet_id: 2252168947361668,\n\
\ column_id: 5005385858869124,\n body: body\n)\nupdated_column = response[:result]\n"
/sheets/{sheetId}/comments/{commentId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: commentId
in: path
required: true
description: ID of the comment
schema:
type: string
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get a comment
description: |
Gets the comment specified by commentId.
operationId: comment-get
tags:
- comments
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Discussion/properties/comments/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "Comment comment = smartsheet.SheetResources.CommentResources.GetComment(\n\
\ 2252168947361668, // sheetId\n 48569348493401200 \
\ // commentId\n);\n"
- lang: Java
source: "Comment comment = smartsheet.sheetResources().commentResources().getComment(\n\
\ 2252168947361668L, // long sheetId\n 4856934849340120L\
\ // long commentId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ commentId: 48569348493401200\n};\n\n// Get comment\nsmartsheet.sheets.getComment(options)\n\
\ .then(function(comment) {\n console.log(comment);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "comment = smartsheet_client.Discussions.get_discussion_comment(\n\
\ 2252168947361668, # sheet_id\n 4856934849340120 # comment_id\n\
)"
- lang: Ruby
source: "comment = smartsheet.sheets.comments.get(\n sheet_id: 2252168947361668,\n\
\ comment_id: 4856934849340120\n)\n"
put:
summary: Edit a comment
description: >
Updates the text of a comment. NOTE: Only the user that created the
comment is permitted to update it.
operationId: comment-edit
tags:
- comments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
type: object
properties:
text:
description: Comment body.
type: string
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1comments~1%7BcommentId%7D/get/responses/200/content/application~1json/schema/allOf/0'
properties:
version:
description: New version of the Sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X PUT\
\ \\\n-d '{\"text\":\"This is the updated comment text.\"}'"
- lang: C#
source: "// Specify edited comment properties\nComment commentSpecification\
\ = new Comment\n{\n Id = 7144101943502724,\n Text = \"This is the updated\
\ comment text\"\n}\n\n// Edit comment\nComment updatedComment = smartsheet.SheetResources.DiscussionResources.CommentResources.UpdateComment(\n\
\ 3285357287499652, // sheetId\n commentSpecification\n);\n"
- lang: JavaScript
source: "// Specify text\nvar body = {\n text: \"This is the updated comment\
\ text.\"\n};\n\n// Set options\nvar options = {\n sheetId: 3285357287499652,\n\
\ commentId: 7144101943502724,\n body: body\n};\n\n// Edit comment\nsmartsheet.sheets.editComment(options)\n\
\ .then(function(updatedComment) {\n console.log(updatedComment);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "comment = smartsheet_client.Discussions.update_comment(\n 3285357287499652,\
\ # sheet_id\n 7144101943502724, # comment_id\n smartsheet.models.Comment({\n\
\ 'text': 'This is the updated comment text'}))\n"
- lang: Ruby
source: "body = {\n text: 'This is the updated comment text'\n}\n\nresponse\
\ = smartsheet.sheets.comments.update(\n sheet_id: 3285357287499652,\n\
\ comment_id: 7144101943502724,\n body: body\n)\nupdated_comment = response[:result]\n"
delete:
summary: Delete a comment
description: |
Deletes the comment specified in the URL.
operationId: comment-delete
tags:
- comments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1comments~1%7BcommentId%7D/put/responses/200/content/application~1json/schema/allOf/0'
properties:
version:
description: New version of the Sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X 'DELETE'"
- lang: C#
source: "smartsheet.SheetResources.CommentResources.DeleteComment(\n 2252168947361668,\
\ // sheetId\n 4952999001909124 // commentId\n);"
- lang: Java
source: "smartsheet.sheetResources().commentResources().deleteComment(\n \
\ 2252168947361668L, // long sheetId\n 4952999001909124L\
\ // long commentId\n );"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ commentId: 4952999001909124\n};\n\n// Delete comment\nsmartsheet.sheets.deleteComment(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "smartsheet_client.Discussions.delete_discussion_comment(\n 2252168947361668,\
\ # sheet_id\n 4952999001909124) # comment_id"
- lang: Ruby
source: "smartsheet.sheets.comments.delete(\n sheet_id: 2252168947361668,\n\
\ comment_id: 4952999001909124\n)"
/sheets/{sheetId}/comments/{commentId}/attachments:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1comments~1%7BcommentId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Attach File or URL to Comment
description: >
Attaches a file to the comment. The URL can be any of the following:
* Normal URL (attachmentType "LINK")
* Box.com URL (attachmentType "BOX_COM")
* Dropbox URL (attachmentType "DROPBOX")
* Egnyte URL (attachmentType "EGNYTE")
* Evernote URL (attachmentType "EVERNOTE")
* Google Drive URL (attachmentType "GOOGLE_DRIVE")
* OneDrive URL (attachmentType "ONEDRIVE")
This operation can be performed using a simple upload or a multipart upload.
operationId: attachments-attachToComment
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
multipart/form-data:
schema:
type: object
properties:
name:
type: string
filename:
type: string
format: binary
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1attachments/post/requestBody/content/application~1json/schema'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/components/schemas/Comment/properties/attachments/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/comments/{commentId}/attachments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/msword\" \\\n-H 'Content-Disposition: attachment; filename=\"\
ProgressReport.docx\"' \\\n-H \"Content-Length: FILE_SIZE\" \\\n-X POST\
\ \\\n--data-binary @ProgressReport.docx"
- lang: C#
source: "Attachment attachment = smartsheet.SheetResources.CommentResources.AttachmentResources.AttachFile(\n\
\ 9283173393803140, // sheetId\n 1234567890234568, \
\ // commentId\n filePath,\n \"application/msword\"\n);\n"
- lang: Java
source: "// Specify file to be attached\nFile file = new File(\"/Users/jdoe/Documents/ProgressReport.docx\"\
);\n\n// Attach file to comment\n Attachment attachment = smartsheet.sheetResources().commentResources().attachmentResources().attachFile(\n\
\ 9283173393803140L, // long sheetId\n 1234567890234568L,\
\ // long commentId\n file,\n \"application/msword\"\
\n );\n"
- lang: JavaScript
source: "// Enable FileStream\nvar fs = require(\"fs\")\n\n// Set options\n\
var options = {\n sheetId: 1696803624483716,\n commentId: 7722333183016324,\n\
\ fileSize: 20765,\n fileName: \"ProgressReport.docx\",\n fileStream:\
\ fs.createReadStream(\"/Users/jdoe/Documents/ProgressReport.docx\")\n};\n\
\n// Attach file to comment\nsmartsheet.sheets.addCommentFileAttachment(options)\n\
\ .then(function(attachment) {\n console.log(attachment);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_attachment = smartsheet_client.Attachments.attach_file_to_comment(\n\
\ 9283173393803140, # sheet_id\n 1234567890234568, # comment_id\n\
\ ('ProgressReport.docx',\n open('/path/to/ProgressReport.docx', 'rb'),\n\
\ 'application/msword')\n)\n"
- lang: Ruby
source: "# Sample 1: attach file from path\nresponse = smartsheet.sheets.comments.attachments.attach_file_from_path(\n\
\ sheet_id: 4583173393803140,\n comment_id: 4293147074291588,\n path:\
\ '/Users/jdoe/Documents/ProgressReport.docx'\n)\nnew_attachment = response[:result]\n\
\n# Sample 2: attach file\nfilename = '/Users/jdoe/Documents/ProgressReport.docx'\n\
file = File.open(filename)\nfile_length = File.size(filename)\n\nresponse\
\ = smartsheet.sheets.comments.attachments.attach_file(\n sheet_id: 4583173393803140,\n\
\ comment_id: 4293147074291588,\n file: file,\n filename: filename,\n\
\ file_length: file_length\n)\nnew_attachment = response[:result]\n"
/sheets/{sheetId}/copy:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/parameters/1'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/parameters/2'
post:
summary: Copy Sheet
description: |
Creates a copy of the specified sheet.
operationId: copy-sheet
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
requestBody:
description: Destination where to create a copy of the specified sheet.
required: true
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: object
properties:
id:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/id'
accessLevel:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/accessLevel'
name:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/name'
permalink:
$ref: '#/components/schemas/Folder/properties/sheets/items/properties/permalink'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/copy?include=data,attachments'\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n-H \"Content-Type:\
\ application/json\"\n-d '{\n \"destinationType\": \"folder\",\n \"destinationId\"\
: 7960873114331012,\n \"newName\": \"newSheetName\"\n}'\n-X POST\n"
- lang: C#
source: "// Specify destination\nContainerDestination destination = new ContainerDestination\
\ {\n DestinationId = 3791509922310020, // long destinationFolderId\n\
\ DestinationType = DestinationType.FOLDER,\n NewName = \"newSheetName\"\
\n};\n\n// Sample 1: Omit 'include' parameter\nSheet sheet = smartsheet.SheetResources.CopySheet(\n\
\ 9283173393803140, // sheetId\n destination,\n\
\ null // IEnumerable\
\ include\n);\n\n// Sample 2: Specify 'include' parameter with value of\
\ \"data\"\nSheet sheet = smartsheet.SheetResources.CopySheet(\n 9283173393803140,\
\ // sheetId\n destination,\n new SheetCopyInclusion[]\
\ { SheetCopyInclusion.DATA }\n);\n"
- lang: Java
source: "// Specify destination\nContainerDestination destination = new ContainerDestination()\n\
\ .setDestinationType(DestinationType.FOLDER)\n .setDestinationId(9283173393803140L)\n\
\ .setNewName(\"newSheetName\");\n\n// Sample 1: Omit 'include' parameter\n\
Sheet sheet = smartsheet.sheetResources().copySheet(\n 4583173393803140L,\
\ // long sheetId\n destination,\n \
\ null // EnumSet\
\ includes\n );\n\n// Sample 2: Specify 'include' parameter with\
\ value of \"data\"\nSheet sheet = smartsheet.sheetResources().copySheet(\n\
\ 4583173393803140L, // long sheetId\n \
\ destination,\n EnumSet.of(SheetCopyInclusion.DATA)\n \
\ );\n"
- lang: JavaScript
source: "// Set destination information\nvar body = {\n destinationType:\
\ \"home\",\n newName: \"newSheetName\"\n};\n\n// Set elements to copy\n\
var params = {\n include: \"attachments,data\",\n includeAll: true\n};\n\
\n// Set options\nvar options = {\n sheetId: 7254137655060356,\n body:\
\ body,\n queryParameters: params\n};\n\n// Copy sheet\nsmartsheet.sheets.copySheet(options)\n\
\ .then(function(copiedSheet) {\n console.log(copiedSheet);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.copy_sheet(\n 4583173393803140,\
\ # sheet_id\n smartsheet.models.ContainerDestination({\n\
\ 'destination_type': 'folder', # folder, workspace, or\
\ home\n 'destination_id': 9283173393803140, # folder_id\n \
\ 'new_name': 'newSheetName'\n })\n)\n"
- lang: Ruby
source: "body = {\n destination_type: 'folder',\n destination_id: 9283173393803140,\n\
\ new_name: 'newSheetName'\n}\n\nsmartsheet.sheets.copy(\n sheet_id: 4583173393803140,\n\
\ body: body\n)\n"
/sheets/{sheetId}/crosssheetreferences:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Create Cross-sheet References
description: Adds a cross-sheet reference between two sheets and defines the
data range for formulas. Each distinct data range requires a new cross-sheet
reference.
operationId: add-crosssheet-reference
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
tags:
- crossSheetReferences
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
requestBody:
description: CrossSheetReference object to create
required: true
content:
application/json:
schema:
oneOf:
- type: object
description: CrossSheetReference object to create which will refer
to the entire columns in the range from startColumnId to endColumnId.
properties:
sourceSheetId:
description: Sheet Id of source sheet.
type: number
name:
description: Friendly name of reference. Auto-generated unless
specified in Create Cross-sheet References.
type: string
endColumnId:
description: Defines ending edge of range when specifying one
or more columns. Must be used with startColumnId.
type: number
startColumnId:
description: Defines beginning edge of range when specifying one
or more columns. Must be used with endColumnId.
type: number
- type: object
description: CrossSheetReference object to create which will refer
to the entire rows in the range from startRowId to endRowId.
properties:
sourceSheetId:
description: Sheet Id of source sheet.
type: number
name:
description: Friendly name of reference. Auto-generated unless
specified in Create Cross-sheet References.
type: string
endRowId:
description: Defines ending edge of range when specifying one
or more rows. Must be used with startRowId.
type: number
startRowId:
description: Defines beginning edge of range when specifying one
or more rows. Must be used with endRowId.
type: number
- type: object
description: CrossSheetReference object to create with specified cell
range.
properties:
sourceSheetId:
description: Sheet Id of source sheet.
type: number
name:
description: Friendly name of reference. Auto-generated unless
specified in Create Cross-sheet References.
type: string
endColumnId:
description: Defines ending edge of range when specifying one
or more columns. Must be used with startColumnId. To specify
an entire column, omit the startRowId and endRowId parameters.
type: number
endRowId:
description: Defines ending edge of range when specifying one
or more rows. Must be used with startRowId. To specify an entire
row, omit the startColumnId and endColumnId parameters.
type: number
startColumnId:
description: Defines beginning edge of range when specifying one
or more columns. Must be used with endColumnId. To specify an
entire column, omit the startRowId and endRowId parameters.
type: number
startRowId:
description: Defines beginning edge of range when specifying one
or more rows. Must be used with endRowId. To specify an entire
row, omit the startColumnId and endColumnId parameters.
type: number
responses:
'200':
description: Result object containing a CrossSheetReference object, corresponding
to what was specified in the request.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/components/schemas/Sheet/properties/crossSheetReferences/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/crosssheetreferences\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\n\t\"name\": \"Sample Time Log\
\ Sheet Range 1\",\n\t\"sourceSheetId\": 154378742065028,\n\t\"startRowId\"\
: 4089096300717956,\n\t\"endRowId\": 2681721417164676,\n\t\"startColumnId\"\
: 824812248557444,\n\t\"endColumnId\": 824812248557444\n}'\n"
- lang: C#
source: "CrossSheetReference xref = new CrossSheetReference();\nxref.Name\
\ = \"Sample Time Log Sheet Range 1\";\nxref.SourceSheetId = 154378742065028;\n\
xref.StartRowId = 4089096300717956;\nxref.EndRowId = 2681721417164676;\n\
xref.StartColumnId = 824812248557444;\nxref.EndColumnId = 824812248557444;\n\
CrossSheetReference newXRef = smartsheet.SheetResources.CrossSheetReferenceResources.CreateCrossSheetReference(\n\
\ 1755440242550660, //sheetId\n xref\n );\n"
- lang: Java
source: "CrossSheetReference xref = new CrossSheetReference();\n xref.setName(\"\
Sample Time Log Sheet Range 1\");\n xref.setSourceSheetId(154378742065028L);\n\
\ xref.setStartRowId(4089096300717956L);\n xref.setEndRowId(2681721417164676L);\n\
\ xref.setStartColumnId(824812248557444L);\n xref.setEndColumnId(824812248557444L);\n\
\nCrossSheetReference newXRef = smartsheet.sheetResources().crossSheetReferenceResources().createCrossSheetReference(\n\
\ 1755440242550660, //sheetId\n xref\n );\n"
- lang: JavaScript
source: "var body = {\n name: \"my cross sheet reference\",\n sourceSheetId:\
\ 154378742065028,\n startRowId: 4089096300717956,\n endRowId: 2681721417164676,\n\
\ \"startColumnId\": 824812248557444,\n\t\"endColumnId\": 824812248557444\n\
};\n\nsmartsheet.sheets.createCrossSheetReference({sheetId: 456745674567,\
\ body: body})\n .then((result) => {\n console.log(\"success\");\n \
\ console.log(JSON.stringify(result));\n })\n .catch((error) => {\n\
\ console.log(\"error\");\n console.log(JSON.stringify(error));\n\
\ });\n"
label: Node.js
- lang: Python
source: "xref = smartsheet.models.CrossSheetReference({\n 'name': 'Sample\
\ Time Log Sheet Range 1',\n 'source_sheet_id': 154378742065028,\n \
\ 'start_row_id': 4089096300717956,\n 'end_row_id': 2681721417164676,\n\
\ 'start_column_id': 824812248557444,\n 'end_column_id': 824812248557444\n\
})\nresult = smartsheet_client.Sheets.create_cross_sheet_reference(\n 1755440242550660,\
\ xref)\n"
- lang: Ruby
source: "smartsheet.sheets.cross_sheet_references.create(\n sheet_id: 8157685695702916,\n\
\ body: {\n name: \"Sample Time Log Sheet Range 1\",\n source_sheet_id:\
\ 154378742065028,\n start_row_id: 4089096300717956,\n end_row_id:\
\ 2681721417164676,\n start_column_id: 824812248557444,\n end_column_id:\
\ 824812248557444\n }\n)\n"
get:
summary: List Cross-sheet References
description: Lists all cross-sheet references for the sheet.
operationId: list-crosssheet-references
tags:
- crossSheetReferences
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: IndexResult object containing an array of CrossSheetReference
objects
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1crosssheetreferences/post/responses/200/content/application~1json/schema/allOf/1/properties/result'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1crosssheetreferences/post/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/crosssheetreferences\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "//Sample 1: List all\nsmartsheet.SheetResources.CrossSheetReferenceResources.ListCrossSheetReferences(\n\
\ 9283173393803140, // sheetId\n null // PaginationParameters\n\
\ );\n\n//Sample 2: Paginate the list\nPaginationParameters paginationParameters\
\ = new PaginationParameters(\n false, // includeAll\n 100, //\
\ pageSize\n 1 // page\n );\nsmartsheet.SheetResources.CrossSheetReferenceResources.ListCrossSheetReferences(\n\
\ 9283173393803140, // sheetId\n paginationParameters\n );\n"
- lang: Java
source: "//Sample 1: List all\nsmartsheet.sheetResources().crossSheetReferenceResources().listCrossSheetReferences(\n\
\ 9283173393803140L, // sheetId\n null // PaginationParameters\n\
\ );\n\n//Sample 2: Paginate the list\nPaginationParameters paginationParameters\
\ = new PaginationParameters(\n false, // includeAll\n 100,\
\ // pageSize\n 1 // page\n );\nsmartsheet.sheetResources().crossSheetReferenceResources().listCrossSheetReferences(\n\
\ 9283173393803140L, // sheetId\n paginationParameters\n\
\ );\n"
- lang: JavaScript
source: "smartsheet.sheets.listCrossSheetReferences({sheetId: 9283173393803140})\n\
\ .then((result) => {\n console.log(\"success\");\n console.log(JSON.stringify(result));\n\
\ })\n .catch((error) => {\n console.log(\"error\");\n console.log(JSON.stringify(error));\n\
\ });\n"
label: Node.js
- lang: Python
source: "result = smartsheet_client.Sheets.list_cross_sheet_references(\n\
\ 9283173393803140)\n"
- lang: Ruby
source: "smartsheet.sheets.cross_sheet_references.list(\n sheet_id: 9283173393803140\n\
)\n"
/sheets/{sheetId}/crosssheetreferences/{crossSheetReferenceId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: crossSheetReferenceId
in: path
schema:
type: number
required: true
description: Cross-sheet Reference Id
get:
summary: Get Cross-sheet Reference
description: Gets the cross-sheet reference specified in the URL.
operationId: get-crosssheet-reference
tags:
- crossSheetReferences
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: CrossSheetReference object
content:
application/json:
schema:
$ref: '#/components/schemas/Sheet/properties/crossSheetReferences/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/crosssheetreferences/{crossSheetReferenceId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "CrossSheetReference xref = smartsheet.SheetResources.CrossSheetReferenceResources.GetCrossSheetReference(\n\
\ 9283173393803140, // sheetId\n 8157685695702916 // crossSheetReferenceId\n\
\ );\n"
- lang: Java
source: "CrossSheetReference xref = smartsheet.sheetResources().crossSheetReferenceResources().getCrossSheetReference(\n\
\ 9283173393803140L, // sheetId\n 8157685695702916L // crossSheetReferenceId\n\
\ );\n"
- lang: JavaScript
source: "smartsheet.sheets.getCrossSheetReference({sheetId: 9283173393803140,\
\ crossSheetReferenceId: 8157685695702916})\n .then((result) => {\n \
\ console.log(\"success\");\n console.log(JSON.stringify(result));\n\
\ })\n .catch((error) => {\n console.log(\"error\");\n console.log(JSON.stringify(error));\n\
\ });\n"
label: Node.js
- lang: Python
source: "result = smartsheet_client.Sheets.get_cross_sheet_reference(\n \
\ 9283173393803140, # sheet_id\n 8157685695702916 # cross_sheet_reference_id\n\
\ )\n"
- lang: Ruby
source: "smartsheet.sheets.cross_sheet_references.get(\n sheet_id: 9283173393803140,\n\
\ cross_sheet_reference_id: 8157685695702916\n)\n"
/sheets/{sheetId}/discussions:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Discussions
description: >
Gets a list of all discussions associated with the specified sheet.
Remember that discussions are containers
for the conversation thread. To see the entire thread, use the include=comments
parameter.
operationId: discussions-list
tags:
- discussions
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of optional elements to include in the
response:
* **attachments** - effective only if comments is present, otherwise ignored
* **comments** - include all comments in threads
schema:
type: string
enum:
- attachments
- comments
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of discussions
type: array
items:
$ref: '#/components/schemas/Proof/properties/discussions/items'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions?include=comments,attachments'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "// Sample 1: Omit 'include' parameter and pagination parameters\n\
PaginatedResult results = smartsheet.SheetResources.DiscussionResources.ListDiscussions(\n\
\ 9283173393803140, // sheetId\n null, \
\ // IEnumerable include\n null \
\ // PaginationParameters\n);\n\n// Sample 2: Specify\
\ 'include' parameter with values of 'COMMENTS' and 'ATTACHMENTS', and 'includeAll'\
\ parameter with value of 'true'\nPaginatedResult results =\
\ smartsheet.SheetResources.DiscussionResources.ListDiscussions(\n 9283173393803140,\
\ // sheetId\n new DiscussionInclusion[] { DiscussionInclusion.COMMENTS,\
\ DiscussionInclusion.ATTACHMENTS },\n new PaginationParameters(\n true,\
\ // includeAll\n null, //\
\ int pageSize\n null) // int page\n);\n"
- lang: Java
source: "// Sample 1: Omit 'include' parameter and pagination parameters\n\
PagedResult results = smartsheet.sheetResources().discussionResources().listDiscussions(\n\
\ 9283173393803140L, // long sheetId\n null, \
\ // PaginationParameters\n null // EnumSet\
\ includes\n );\n\n// Sample 2: Specify pagination parameter 'includeAll'\n\
PaginationParameters parameters = new PaginationParameters()\n .setIncludeAll(true);\n\
\n// List discussions (specify 'include' parameter with values of 'COMMENTS'\
\ and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true')\n\
PagedResult results = smartsheet.sheetResources().discussionResources().listDiscussions(\n\
\ 9283173393803140L, // long sheetId\n parameters,\n \
\ EnumSet.of(DiscussionInclusion.COMMENTS, DiscussionInclusion.ATTACHMENTS)\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 3138415114905476\n};\n\
\n// List discussions\nsmartsheet.sheets.getDiscussions(options)\n .then(function(discussionList)\
\ {\n console.log(discussionList);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Discussions.get_all_discussions(\n\
\ 9283173393803140, # sheet_id\n include_all=True)\ndiscussions\
\ = response.data\n\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Discussions.get_all_discussions(\n\
\ 9283173393803140, # sheet_id\n page_size=10,\n page=1)\npages\
\ = response.total_pages\ndiscussions = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.discussions.list(\n sheet_id: 4583173393803140\n\
)\ndiscussions = response[:data]\n"
post:
summary: Create a Discussion
description: >
Creates a new discussion on a sheet. To create a discussion with an
attachment please use "multipart/form-data" content type.
operationId: discussions-create
tags:
- discussions
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
type: object
properties:
comment:
description: Comment.
type: object
properties:
text:
description: Comment text.
type: string
multipart/form-data:
schema:
type: object
properties:
discussion:
type: object
description: Discussion.
properties:
comment:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions/post/requestBody/content/application~1json/schema/properties/comment'
title:
description: Title for the attachment. Only used with an attachment.
type: string
file:
description: File to attach to the new comment. Only used with an
attachment.
type: string
format: binary
encoding:
discussion:
contentType: application/json
file:
contentType: application/octet-stream
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "# Example request: create discussion on sheet (without attachment)\n\
\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"comment\": {\"text\":\"This\
\ text is the body of the first comment\"}}'\n\n# Example request: create\
\ discussion on sheet (with attachment)\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ multipart/form-data\" \\\n-X POST \\\n-F 'discussion={ \"comment\": {\
\ \"text\": \"This text is the body of the first comment\" } };type=application/json'\
\ \\\n-F \"file=@file_to_attach;type=application/octet-stream\""
- lang: C#
source: "// Example request: create discussion on sheet (without attachment)\n\
\n// Create discussion (including the comment)\nDiscussion discussionSpecification\
\ = new Discussion\n{\n Comment = new Comment\n {\n Text = \"This text\
\ is the body of the first comment\"\n },\n Comments = null //\
\ workaround for SDK issue\n};\n\n// Add discussion to sheet\nDiscussion\
\ newDiscussion = smartsheet.SheetResources.DiscussionResources.CreateDiscussion(\n\
\ 9283173393803140, // sheetId\n discussionSpecification\n\
);\n\n// Example request: create discussion on sheet (with attachment)\n\
\n// Create discussion (including the comment)\nDiscussion discussionSpecification\
\ = new Discussion\n{\n Comment = new Comment\n {\n Text = \"This text\
\ is the body of the first comment\"\n },\n Comments = null //\
\ workaround for SDK issue\n};\n\n// Add discussion (including comment with\
\ attachment) to sheet\nDiscussion newDiscussion = smartsheet.SheetResources.DiscussionResources.CreateDiscussionWithAttachment(\n\
\ 9283173393803140, // sheetId\n discussionSpecification,\n\
\ filePath,\n \"application/octet-stream\"\n);\n"
- lang: Java
source: "// Example request: create discussion on sheet (without attachment)\n\
\n// Create comment\nComment commentSpecification = new Comment()\n \
\ .setText(\"This text is the body of the first comment\");\n\n// Create\
\ discussion (including the comment)\n Discussion discussionSpecification\
\ = new Discussion()\n .setComment(commentSpecification)\n \
\ .setComments(null); // workaround for SDK issue\n\n// Add discussion\
\ to sheet\n Discussion newDiscussion = smartsheet.sheetResources().discussionResources().createDiscussion(\n\
\ 9283173393803140L, // long sheetId\n discussionSpecification\n\
\ );\n\n// Example request: create discussion on sheet (with attachment)\n\
\n// Create comment\n Comment commentSpecification = new Comment()\n\
\ .setText(\"This text is the body of the first comment\");\n\n//\
\ Create discussion (including the comment)\n Discussion discussionSpecification\
\ = new Discussion()\n .setComment(commentSpecification)\n \
\ .setComments(null); // workaround for SDK issue\n\n File file\
\ = new File(filePath);\n\n// Add discussion (including comment with attachment)\
\ to sheet\n Discussion newDiscussion = smartsheet.sheetResources().discussionResources().createDiscussionWithAttachment(\n\
\ 9283173393803140L, // long sheetId\n discussionSpecification,\n\
\ file,\n \"application/octet-stream\"\n );\n"
- lang: JavaScript
source: "// Example request: create discussion on sheet (without attachment)\n\
\n// Specify discussion\nvar discussion = {\n \"comment\": {\n \"text\"\
: \"This text is the body of the first comment\"\n }\n};\n\n// Set options\n\
var options = {\n sheetId: 2252168947361668,\n body: discussion\n };\n\
\n// Add discussion to sheet\nsmartsheet.sheets.createDiscussion(options)\n\
\ .then(function(newDiscussion) {\n console.log(newDiscussion);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n\n// Example\
\ request: create discussion on sheet (with attachment)\n\n// Multipart\
\ operations are not supported by the Node SDK. Instead, see instructions\
\ to Create Discussion on Sheet, and then Attach File to Comment.\n"
label: Node.js
- lang: Python
source: "# Example request: create discussion on sheet (without attachment)\n\
\nresponse = smartsheet_client.Discussions.create_discussion_on_sheet(\n\
\ 9283173393803140, # sheet_id\n smartsheet.models.Discussion({\n\
\ 'comment': smartsheet.models.Comment({\n 'text': 'This text is\
\ the body of the first comment'\n })\n })\n)\n\n# Example request:\
\ create discussion on sheet (with attachment)\n\nresponse = smartsheet_client.Discussions.create_discussion_on_sheet_with_attachment(\n\
\ 9283173393803140, # sheet_id\n smartsheet.models.Discussion({\n\
\ 'comment': smartsheet.models.Comment({\n 'text': 'This text is\
\ the body of the first comment'\n })\n }),\n ('photo.jpg', open('/path/to/photo.jpg',\
\ 'rb'), 'image/jpeg')\n)"
- lang: Ruby
source: "# Example request: create discussion on sheet (without attachment)\n\
\n# Set options\nbody = {\n comment: {\n text: 'This text is the body\
\ of the first comment'\n }\n}\n\n# Create discussion on sheet\nresponse\
\ = smartsheet.sheets.discussions.create_on_sheet(\n sheet_id: 4583173393803140,\n\
\ body: body\n)\nnew_discussion = response[:result]\n\n# Example request:\
\ create discussion on sheet (with attachment)\n\n# Multipart operations\
\ are not supported by the Ruby SDK. Instead, see instructions to Create\
\ Discussion on Sheet, and then Attach File to Comment.\n"
/sheets/{sheetId}/discussions/{discussionId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: discussionId
in: path
required: true
description: ID of the discussion
schema:
type: string
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Discussion
description: |
Gets the discussion specified by discussionId.
operationId: discussion-get
tags:
- discussions
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Proof/properties/discussions/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "Discussion discussion = smartsheet.SheetResources.DiscussionResources.GetDiscussion(\n\
\ 9283173393803140, // sheetId\n 0123456789012345 \
\ // discussionId\n);\n"
- lang: Java
source: "Discussion discussion = smartsheet.sheetResources().discussionResources().getDiscussion(\n\
\ 9283173393803140L, // long sheetId\n 0123456789012345L\
\ // long discussionId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ discussionId: 2331373580117892\n};\n\n// Get discussion\nsmartsheet.sheets.getDiscussions(options)\n\
\ .then(function(discussion) {\n console.log(discussion);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "discussion = smartsheet_client.Discussions.get_discussion(\n 9283173393803140,\
\ # sheet_id\n 0123456789012345) # discussion_id\n\n# discussion\
\ is an instance of smartsheet.models.Discussion\n"
- lang: Ruby
source: "discussion = smartsheet.sheets.discussions.get(\n sheet_id: 4583173393803140,\n\
\ discussion_id: 3962273862576004\n)\n"
delete:
summary: Delete a Discussion
description: |
Deletes the discussion specified in the URL.
operationId: discussion-delete
tags:
- discussions
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\\\n-X 'DELETE'"
- lang: C#
source: "smartsheet.SheetResources.DiscussionResources.DeleteDiscussion(\n\
\ 9283173393803140, // sheetId\n 0123456789012345 \
\ // discussionId\n);\n"
- lang: Java
source: "smartsheet.sheetResources().discussionResources().deleteDiscussion(\n\
\ 9283173393803140L, // long sheetId\n 0123456789012345L\
\ // long discussionId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ discussionId: 991393444325252\n};\n\n// Delete discussion\nsmartsheet.sheets.deleteDiscussion(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Discussions.delete_discussion(\n 9283173393803140,\
\ # sheet_id\n 0123456789012345) # discussion_id\n"
- lang: Ruby
source: "smartsheet.sheets.discussions.delete(\n sheet_id: 4583173393803140,\n\
\ discussion_id: 3962273862576004\n)\n"
/sheets/{sheetId}/discussions/{discussionId}/attachments:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions~1%7BdiscussionId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Discussion Attachments
description: |
Gets a list of all attachments that are in the discussion.
operationId: discussion-listAttachments
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of attachments
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/attachments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult attachments\
\ = smartsheet.SheetResources.DiscussionResources.AttachmentResources.ListAttachments(\n\
\ 9283173393803140, // sheetId\n 1234567890123456, \
\ // discussionId\n null // PaginationParameters\n\
);\n"
- lang: Java
source: "// Omit pagination\nPagedResult attachments = smartsheet.sheetResources().discussionResources().attachmentResources().getAttachments(\n\
\ 9283173393803140L, // long sheetId\n 1234567890123456L,\
\ // long discussionId\n null // PaginationParameters\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ discussionId: 3962273862576004\n};\n\n// List discussion attachments\n\
smartsheet.sheets.listDiscussionAttachments(options)\n .then(function(attachmentsList)\
\ {\n console.log(attachmentsList);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List All\nresponse = smartsheet_client.Attachments.list_discussion_attachments(\n\
\ 9283173393803140, # sheet_id\n 1234567890123456, # discussion_id\n\
\ include_all=True)\nattachments = response.data\n\n# Sample 2: Paginate\
\ the list\nresponse = smartsheet_client.Attachments.list_discussion_attachments(\n\
\ 9283173393803140, # sheet_id\n 1234567890123456, # discussion_id\n\
\ page_size=10,\n page=1)\npages = response.total_pages\nattachments =\
\ response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.discussions.attachments.list(\n sheet_id:\
\ 9283173393803140,\n discussion_id: 1234567890123456\n)\nattachments =\
\ response[:data]\n"
/sheets/{sheetId}/discussions/{discussionId}/comments:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions~1%7BdiscussionId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Create a comment
description: >
Adds a comment to a discussion. To create a comment with an attachment
please use "multipart/form-data" content type.
operationId: comments-create
tags:
- comments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1comments~1%7BcommentId%7D/put/requestBody/content/application~1json/schema'
multipart/form-data:
schema:
type: object
properties:
comment:
description: Comment.
type: object
properties:
text:
description: Comment text.
type: string
file:
description: File to attach to the new comment. Only used with an
attachment.
type: string
format: binary
encoding:
comment:
contentType: application/json
file:
contentType: application/octet-stream
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/components/schemas/Discussion/properties/comments/items'
x-codeSamples:
- lang: cURL
source: "# Example request: add comment (without attachment)\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"text\":\"This is a new comment.\"\
}'\n\n# Example request: add comment (with attachment)\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/discussions/{discussionId}/comments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ multipart/form-data\" \\\n-X POST \\\n-F 'comment={ \"text\":\"This is\
\ a new comment.\" };type=application/json' \\\n-F \"file=@insurance_benefits.pdf;type=application/octet-stream\""
- lang: C#
source: "// Example request: add comment (without attachment)\n\n// Create\
\ comment\nComment commentSpecification = new Comment\n{\n Text = \"This\
\ is a new comment.\"\n};\n\n// Add comment to discussion\nComment newComment\
\ = smartsheet.SheetResources.DiscussionResources.CommentResources.AddComment(\n\
\ 2252168947361668, // sheetId\n 3962273862576004, \
\ // discussionId\n commentSpecification\n);\n\n// Example request:\
\ add comment (with attachment)\n\n// Create comment\nComment commentSpecification\
\ = new Comment\n{\n Text = \"This is a new comment.\"\n};\n\n// Add comment\
\ (with attachment) to discussion\nComment newComment = smartsheet.SheetResources.DiscussionResources.CommentResources.AddCommentWithAttachment(\n\
\ 2252168947361668, // sheetId\n 3962273862576004, \
\ // discussionId\n commentSpecification,\n filePath,\n\
\ \"application/octet-stream\"\n);\n"
- lang: Java
source: "// Example request: add comment (without attachment)\n\n// Create\
\ comment\nComment commentSpecification = new Comment()\n .setText(\"\
This is a new comment.\");\n\n// Add comment to discussion\n Comment\
\ newComment = smartsheet.sheetResources().discussionResources().commentResources().addComment(\n\
\ 2252168947361668L, // long sheetId\n 3962273862576004L,\
\ // long discussionId\n commentSpecification\n );\n\
\n// Example request: add comment (with attachment)\n\n// Create comment\n\
\ Comment commentSpecification = new Comment()\n .setText(\"\
This is a new comment.\");\n\n// Add comment (with attachment) to discussion\n\
\ File file = new File(filePath);\n smartsheet.sheetResources().discussionResources().commentResources().addCommentWithAttachment(\n\
\ 2252168947361668L, // long sheetId\n 3962273862576004L,\
\ // long discussionId\n commentSpecification,\n file,\n\
\ \"application/octet-stream\"\n );\n"
- lang: JavaScript
source: "// Example request: add comment (without attachment)\n\n// Specify\
\ comment\nvar comment = { \"text\": \"This is a new comment.\" };\n\n//\
\ Set options\nvar options = {\n sheetId: 2252168947361668,\n discussionId:\
\ 3962273862576004,\n body: comment\n };\n\n// Add comment to discussion\n\
smartsheet.sheets.addDiscussionComment(options)\n .then(function(newComment)\
\ {\n console.log(newComment);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n\n// Example request: add comment (with attachment)\n\
\n// Multipart operations are not supported by the Node SDK. Instead, see\
\ instructions to Add Comment, and then Attach File to Comment.\n"
label: Node.js
- lang: Python
source: "# Example request: add comment (without attachment)\n\nresponse =\
\ smartsheet_client.Discussions.add_comment_to_discussion(\n 2252168947361668,\
\ # sheet_id\n 3962273862576004, # discussion_id\n smartsheet.models.Comment({\n\
\ 'text': 'This is a new comment.'\n })\n)\n\n# Example request: add\
\ comment (with attachment)\n\n# Create comment\ncomment = smartsheet.models.Comment({\n\
\ 'text': 'This is a new comment.'\n})\n\n# Add comment (with attachment)\
\ to discussion\nresponse = smartsheet_client.Discussions.add_comment_to_discussion_with_attachment(\n\
\ 2252168947361668, # sheet_id\n 3962273862576004, \
\ # discussion_id\n comment,\n ('image.png', open('/path/to/image.png',\
\ 'rb'), 'image/png')\n)\n"
- lang: Ruby
source: "# Example request: add comment (without attachment)\n\nbody = {\n\
\ text: 'This is a new comment.'\n}\n\nresponse = smartsheet.sheets.comments.add(\n\
\ sheet_id: 2252168947361668,\n discussion_id: 3962273862576004,\n body:\
\ body\n)\nnew_comment = response[:result]\n\n# Example request: add comment\
\ (with attachment)\n\n# Multipart operations are not supported by the Ruby\
\ SDK. Instead, see instructions to Add Comment, and then Attach File to\
\ Comment.\n"
/sheets/{sheetId}/emails:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1favorites/post/parameters/0'
post:
summary: Send Sheet via Email
description: Sends the sheet as a PDF attachment via email to the designated
recipients.
operationId: sheet-send
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
requestBody:
description: >
[SheetEmail
object](../../tag/sendViaEmailObjects#section/Sheet-Email-Object)
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1emails/post/requestBody/content/application~1json/schema'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/emails \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"sendTo\" : [{\"email\": \"john.doe@smartsheet.com\"\
}, {\"groupId\": 2258118617917316}], \"subject\": \"Check these rows out!\"\
, \"message\": \"Here is the Sheet I mentioned in our meeting.\", \"ccMe\"\
: false, \"format\": \"PDF\", \"formatDetails\": {\"paperSize\": \"A4\"\
}}'\n"
- lang: C#
source: "// Specify recipients\nRecipient[] recipients = new Recipient[] {\n\
\ new Recipient { Email = \"john.doe@smartsheet.com\" },\n new Recipient\
\ { GroupId = 2258118617917316 }\n};\n\n// Configure email\nSheetEmail sheetEmail\
\ = new SheetEmail {\n SendTo = recipients,\n Subject = \"Check this report\
\ out!\",\n Message = \"Here are the rows I mentioned in our meeting\"\
,\n CcMe = false,\n Format = SheetEmailFormat.PDF,\n FormatDetails =\
\ new FormatDetails { PaperSize = PaperSize.A4 }\n};\n\n// Send sheet via\
\ email\nsmartsheet.SheetResources.SendSheet(4293147074291588, sheetEmail);\
\ // sheetId\n"
- lang: Java
source: "// Specify individual recipient\nRecipientEmail recipientEmail =\
\ new RecipientEmail.AddRecipientEmailBuilder()\n .setEmail(\"john.doe@smartsheet.com\"\
)\n .build();\n\n// Specify group recipient\nRecipientGroup recipientGroup\
\ = new RecipientGroup.AddRecipientGroupBuilder()\n .setGroupId(2258118617917316L)\n\
\ .build();\n\n// Set recipients\nList recipients = Arrays.asList(recipientEmail,recipientGroup);\n\
\n// Set format details\nFormatDetails formatDetails = new FormatDetails();\n\
formatDetails.setPaperSize(PaperSize.A0);\n\n// Configure email\nSheetEmail\
\ email = new SheetEmail.AddSheetEmailBuilder()\n .setSendTo(recipients)\n\
\ .setSubject(\"Check these rows out!\")\n .setMessage(\"\
Here are the rows I mentioned in our meeting\")\n .setCcMe(false)\n\
\ .setFormat(SheetEmailFormat.PDF)\n .setFormatDetails(formatDetails)\n\
\ .build();\n\n// Send sheet via email\nsmartsheet.sheetResources().sendSheet(4293147074291588L,\
\ email); // sheetId\n"
- lang: JavaScript
source: "// Configure email\nvar email = {\n \"sendTo\": [\n {\n \
\ \"email\": \"john.doe@smartsheet.com\"\n },\n {\n \"groupId\"\
: 2258118617917316\n }\n ],\n \"subject\": \"Check these rows out!\"\
,\n \"message\": \"Here are the rows I mentioned in our meeting\",\n \"\
ccMe\": false,\n \"format\": \"PDF\",\n \"formatDetails\": {\n \"paperSize\"\
: \"A4\"\n }\n};\n\n// Set options\nvar options = {\n body: email,\n \
\ sheetId: 2252168947361668\n};\n\n// Send sheet via email\nsmartsheet.sheets.sendSheetViaEmail(options)\n\
\ .then(function(data) {\n console.log(data);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.send_sheet(\n 4293147074291588,\
\ # sheet_id\n smartsheet.models.SheetEmail({\n 'send_to':\
\ [\n smartsheet.models.Recipient({'email': 'john.doe@smartsheet.com'}),\n\
\ smartsheet.models.Recipient({'group_id': 2258118617917316})\n \
\ ],\n 'subject': 'Check these rows out!',\n 'message': 'Here are\
\ the rows I mentioned in our meeting.',\n 'cc_me': False,\n 'format':\
\ 'PDF',\n 'format_details': smartsheet.models.FormatDetails({\n \
\ 'paper_size': 'A4'\n })\n })\n)\n"
- lang: Ruby
source: "# Configure email\nbody = {\n send_to: [\n {\n email: 'john.doe@smartsheet.com'\n\
\ },\n {\n group_id: 3051008235464580\n }\n ],\n subject:\
\ 'Check these rows out!',\n message: 'Here are the rows I mentioned in\
\ our meeting',\n cc_me: false,\n format: 'PDF',\n format_details: {\n\
\ paper_size: 'LEGAL'\n }\n}\n\n# Send sheet\nresponse = smartsheet.sheets.send_via_email(\n\
\ sheet_id: 3294745817573252,\n body: body\n)\n"
/sheets/{sheetId}/move:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1favorites/post/parameters/0'
post:
summary: Move Sheet
description: >
Moves the specified sheet to a new location.
When a sheet that is shared to one or more users and/or groups is moved into
or out of a workspace, those sheet-level shares are preserved.
operationId: move-sheet
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
requestBody:
description: Destination to move the specified sheet.
required: true
content:
application/json:
schema:
type: object
properties:
destinationId:
description: The Id of the destination container (when copying or
moving a sheet or a folder). Required if destinationType is "folder"
or "workspace". If destinationType is "home", this value must
be null.
type: number
destinationType:
description: Type of the destination container.
type: string
nullable: true
enum:
- folder
- home
- workspace
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1copy/post/responses/200/content/application~1json/schema/allOf/1/properties/result'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/move \\\n-H\
\ \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-d '{\n \"destinationType\": \"folder\",\n \"\
destinationId\": 7960873114331012\n}' \\\n-X POST\n"
- lang: C#
source: "// Specify destination\nContainerDestination destination = new ContainerDestination\
\ {\n DestinationId = 7960873114331012, // destinationFolderId\n\
\ DestinationType = DestinationType.FOLDER,\n};\n\n// Move sheet\nSheet\
\ sheet = smartsheet.SheetResources.MoveSheet(\n 4583173393803140, \
\ // sheetId\n destination\n);\n"
- lang: Java
source: "// Specify destination\nContainerDestination destination = new ContainerDestination();\n\
\ destination.setDestinationType(DestinationType.FOLDER)\n \
\ .setDestinationId(7960873114331012L);\n\n// Move sheet\nSheet sheet =\
\ smartsheet.sheetResources().moveSheet(\n 4583173393803140L, \
\ // long sheetId\n destination\n );\n"
- lang: JavaScript
source: "// Set destination information\nvar body = {\n destinationType:\
\ \"folder\",\n destinationId: 7960873114331012\n};\n\n// Set options\n\
var options = {\n sheetId: 4583173393803140,\n body: body\n};\n\n// Move\
\ sheet\nsmartsheet.sheets.moveSheet(options)\n .then(function(movedSheet)\
\ {\n console.log(movedSheet);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "sheet = smartsheet_client.Sheets.move_sheet(\n 4583173393803140,\
\ # sheet_id\n smartsheet.models.ContainerDestination({\n\
\ 'destination_type': 'folder', # folder, workspace, or home\n\
\ 'destination_id': 7960873114331012 # folder_id\n })\n)\n"
- lang: Ruby
source: "body = {\n destination_type: 'folder',\n destination_id: 7960873114331012\n\
}\n\nsheet = smartsheet.sheets.move(\n sheet_id: 4583173393803140,\n body:\
\ body\n)\n"
/sheets/{sheetId}/proofs:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
summary: List Proofs
description: |
Gets a list of all proofs for a given sheet.
operationId: proofs-getAllProofs
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of all proofs
type: array
items:
$ref: '#/components/schemas/Row/properties/proofs'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
/sheets/{sheetId}/proofs/{proofId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: proofId
in: path
required: true
description: Proof Id of the original proof
schema:
type: string
- $ref: '#/paths/~1contacts/parameters/0'
get:
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of optional elements to include in the
response.
schema:
type: string
enum:
- attachments
- discussions
summary: Get Proof
description: >
Gets the proof specified in the URL. Returns the proof, which is
optionally populated with discussion and attachment objects.
operationId: proofs-get
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Row/properties/proofs'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}?include=attachments,discussions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
delete:
summary: Delete Proof
description: >
Deletes the proof including all versions. The proofId must be for the
original version.
operationId: proofs-delete
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
put:
summary: Update Proof Status
description: |
Sets the proof status as either complete or incomplete.
operationId: proofs-update
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
requestBody:
content:
application/json:
schema:
type: object
properties:
isCompleted:
type: boolean
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D/get/responses/200/content/application~1json/schema/allOf/0'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Disposition:\
\ attachment; filename=\"abc.bmp\"\"\n-X PUT\n"
/sheets/{sheetId}/proofs/{proofId}/attachments:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Proof Attachments
description: >
Gets a list of all attachments that are in the proof, excluding
discussion-level attachments in the proof.
operationId: proofs-listAttachments
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of proof attachments
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/attachments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
post:
summary: Attach File to Proof
description: |
Attaches a file to the proof.
operationId: proofs-attachToProof
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D~1attachments/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/attachments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ image/gif\" \\\n-H \"Content-Disposition: attachment; filename=\"giphy.gif\"\
\" \\\n-X POST \\\n--data-binary \"@home/giphy.gif\"\n"
/sheets/{sheetId}/proofs/{proofId}/discussions:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Proof Discussions
description: |
Gets a list of all discussions that are in the proof.
operationId: proofs-listDiscussions
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of proof discussions
type: array
items:
$ref: '#/components/schemas/Proof/properties/discussions/items'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/discussions'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
post:
summary: Create Proof Discussion
description: |
Creates a discussion on a proof.
operationId: proofs-createDiscussion
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions/post/requestBody/content/application~1json/schema'
multipart/form-data:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions/post/requestBody/content/multipart~1form-data/schema'
encoding:
discussion:
contentType: application/json
file:
contentType: application/octet-stream
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D~1discussions/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "// Sample 1: create proof discussion (without attachment)\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/discussions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ multipart/form-data \\\n-X POST \\\n--data-binary \"@/home/Downloads/test_b\
\ (4).pdf\"\n\n// Sample 2: create proof discussion (with attachment)\n\
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/discussions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ multipart/form-data \\\n-X POST \\\n-F 'discussion={ \"comment\": { \"\
text\": \"This text is the body of the first comment\" } };type=application/json'\
\ \\\n-F \"file=@/home/Downloads/test_b (4).pdf;type=application/octet-stream\"\
\n"
/sheets/{sheetId}/proofs/{proofId}/requestactions:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Proof Request Actions
description: >
Gets a summarized list of all request actions associated with the
specified proof.
operationId: proofs-listRequestActions
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of proof request actions
type: array
items:
type: object
properties:
user:
description: >
`User` object containing `name` and `email` of
the user performing the action.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
actionStatus:
description: Proof request action status.
type: string
enum:
- APPROVED
- PENDING
- REJECTED
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/requestactions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
/sheets/{sheetId}/proofs/{proofId}/requests:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
delete:
summary: Delete Proof Requests
description: |
Deletes all proof requests in a proof.
operationId: proofs-deleteProofRequests
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/requests\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
post:
summary: Create Proof Request
description: |
Creates a proof request.
operationId: proofs-createProofRequests
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProofRequest/allOf/0'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D~1requests/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
allOf:
- $ref: '#/components/schemas/ProofRequest/allOf/0'
type: object
properties:
id:
description: Proof request Id.
type: number
proofId:
description: Proof Id of the original proof.
type: number
sentBy:
description: >
`User` object containing `name` and `email` of the
sender.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
sentAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
isDownloadable:
description: Indicates whether the description is downloadable.
type: boolean
status:
description: Proof request status.
type: string
enum:
- ACTIVE
- EXPIRED
- PROOF_DELETED
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/requests\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\n\t\"sendTo\": [{\n\t\t\"email\"\
: \"john.doe@smartsheet.com\"\n\t}],\n\t\"subject\": \"This is a test.\"\
\n}'\n"
/sheets/{sheetId}/proofs/{proofId}/versions:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Proof Versions
description: >
Gets a list of all versions of the given proofId in order from newest to
oldest.
operationId: proofs-getVersions
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of proof versions
type: array
items:
$ref: '#/components/schemas/Row/properties/proofs'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/versions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
delete:
summary: Delete Proof Version
description: |
Deletes a proof version. Proof Id must be a current version proof Id.
operationId: proofs-deleteVersion
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/versions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
post:
summary: Create Proof Version
description: |
Creates a proof version. Proof Id must be for the original proof.
operationId: proofs-createVersion
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
multipart/form-data:
schema:
type: object
properties:
name:
type: string
filename:
type: string
format: binary
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1attachments/post/requestBody/content/application~1json/schema'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D~1versions/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1proofs~1%7BproofId%7D~1versions/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/versions\
\ \\\n-H \"Content-Disposition: attachment; filename=\"error.gif\"\" \\\n\
-H \"Content-Type: image/gif\" \\\n-X POST \\\n--data-binary \"@/home/Downloads/giphy.gif\"\
\n"
/sheets/{sheetId}/publish:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Sheet Publish Status
description: |
Gets the sheet's 'Publish' settings.
operationId: get-sheetPublish
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: OK
content:
application/json:
schema:
description: Describes the sheet's publish settings.
type: object
properties:
icalEnabled:
description: If **true**, a webcal is available for the calendar
in the sheet.
type: boolean
icalUrl:
description: >
URL for **iCal** view of the published sheet. Only
returned in a response if **icalEnabled = true**.
readOnlyFullAccessibleBy:
description: >
Indicates who can access the 'Read-Only Full' view of the
published sheet:
* ALL - available to anyone who has the link.
* ORG - available only to members of the sheet owner's Smartsheet
organization account.
* SHARED - available only to users shared to the item.
Only returned in the response if **readOnlyFullEnabled = true**.
type: string
enum:
- ALL
- ORG
- SHARED
readOnlyFullDefaultView:
description: >
Indicates which view the user has set for a read-only,
default view of the published sheet. Must be one of the
listed enum values.
type: string
enum:
- CALENDAR
- CARD
- GRID
readOnlyFullEnabled:
description: If **true**, a rich version of the sheet is published
with the ability to download row attachments and discussions.
type: boolean
readOnlyFullShowToolbar:
description: Indicates whether the left nav toolbar is displayed.
The default, or **true**, is to display the toolbar. If **false**,
hides the toolbar.
type: boolean
deprecated: true
readOnlyFullUrl:
description: URL for 'Read-Only Full' view of the published sheet.
Only returned in a response if **readOnlyFullEnabled = true.
type: string
readOnlyLiteEnabled:
description: If **true**, a lightweight version of the sheet is
published without row attachments and discussions.
type: boolean
readOnlyLiteSslUrl:
description: URL for 'Read-Only' view of the published sheet when
SSL is enabled.
type: string
readOnlyLiteUrl:
description: URL for 'Read-Only HTML' view of the published sheet.
Only returned in a response if **readOnlyLiteEnabled = true**.
type: string
readWriteAccessibleBy:
description: >
Indicates who can access the 'Edit by Anyone' view of the
published sheet:
* ALL - available to anyone who has the link.
* ORG - available only to members of the sheet owner's Smartsheet
organization account.
* SHARED - available only to users shared to the item.
Only returned in the response if **readWriteEnabled = true**.
type: string
enum:
- ALL
- ORG
- SHARED
readWriteDefaultView:
description: >
Indicates which view the user has set for a read-write,
default view of the published sheet. Must be one of the
listed enum values.
type: string
enum:
- CALENDAR
- CARD
- GRID
readWriteEnabled:
description: If **true**,a rich version of the sheet is published
with the ability to edit cells and manage attachments and discussions.
type: boolean
readWriteShowToolbar:
description: Indicates whether the left nav toolbar is displayed.
The default, or **true**, is to display the toolbar. If **false**,
hides the toolbar.
type: boolean
deprecated: true
readWriteUrl:
description: URL for 'Edit by Anyone' view of the published sheet.
Only returned in a response if **readWriteEnabled = true**.
type: string
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/publish \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "SheetPublish status = smartsheet.SheetResources.GetPublishStatus(\n\
\ 4583173393803140 // sheetId\n);\n"
- lang: Java
source: "SheetPublish status = smartsheet.sheetResources().getPublishStatus(\n\
\ 4583173393803140L, // long sheetId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 4583614634583940\n};\n\
\n// Get sheet publish status\nsmartsheet.sheets.getPublishStatus(options)\n\
\t.then(function(status) {\n\t\tconsole.log(status);\n\t})\n\t.catch(function(error)\
\ {\n\t\tconsole.log(error);\n\t});\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.get_publish_status(\n 4583173393803140)\
\ # sheet_id\nstatus = response.result\n# status is a smartsheet.models.SheetPublish\
\ object\n"
- lang: Ruby
source: "status = smartsheet.sheets.get_publish_status(\n sheet_id: 4583173393803140\n\
)\n"
put:
summary: Set Sheet Publish Status
description: >
Sets the publish status of the sheet and returns the new status,
including the URLs of any enabled publishings.
operationId: set-sheetPublish
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
description: >
SheetPublish object.
For Read Only, if you do not specify a value for **readOnlyFullAccessibleBy**,
the value defaults
to the organization-level 'Sheet Publishing' setting (if the sheet owner
belongs to an organization account)
or to **ALL** (if the sheet owner does not belong to an organization account).
For Read Write, if you do not specify a value for **readWriteAccessibleBy**,
the value defaults
to the organization-level 'Sheet Publishing' setting (if the sheet owner
belongs to an organization account)
or to **ALL** (if the sheet owner does not belong to an organization account).
content:
application/json:
schema:
description: Describes the sheet's publish settings. Used as a request
body to set publish status.
type: object
properties:
icalEnabled:
description: If **true**, a webcal is available for the calendar
in the sheet.
type: boolean
readOnlyFullAccessibleBy:
description: >
Indicates who can access the 'Read-Only Full' view of the
published sheet:
* ALL - available to anyone who has the link.
* ORG - available only to members of the sheet owner's Smartsheet
organization account.
* SHARED - available only to users shared to the item.
Only returned in the response if **readOnlyFullEnabled = true**.
type: string
enum:
- ALL
- ORG
- SHARED
readOnlyFullDefaultView:
description: >
Indicates which view the user has set for a read-only,
default view of the published sheet. Must be one of the
listed enum values.
type: string
enum:
- CALENDAR
- CARD
- GRID
readOnlyFullEnabled:
description: If **true**, a rich version of the sheet is published
with the ability to download row attachments and discussions.
type: boolean
readOnlyFullShowToolbar:
description: Indicates whether the left nav toolbar is displayed.
The default, or **true**, is to display the toolbar. If **false**,
hides the toolbar.
type: boolean
deprecated: true
readOnlyLiteEnabled:
description: If **true**, a lightweight version of the sheet is
published without row attachments and discussions.
type: boolean
readWriteAccessibleBy:
description: >
Indicates who can access the 'Edit by Anyone' view of the
published sheet:
* ALL - available to anyone who has the link.
* ORG - available only to members of the sheet owner's Smartsheet
organization account.
* SHARED - available only to users shared to the item.
Only returned in the response if **readWriteEnabled = true**.
type: string
enum:
- ALL
- ORG
- SHARED
readWriteDefaultView:
description: >
Indicates which view the user has set for a read-write,
default view of the published sheet. Must be one of the
listed enum values.
type: string
enum:
- CALENDAR
- CARD
- GRID
readWriteEnabled:
description: If **true**,a rich version of the sheet is published
with the ability to edit cells and manage attachments and discussions.
type: boolean
readWriteShowToolbar:
description: Indicates whether the left nav toolbar is displayed.
The default, or **true**, is to display the toolbar. If **false**,
hides the toolbar.
type: boolean
deprecated: true
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1publish/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1publish/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/publish \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{\"readOnlyLiteEnabled\": true,\"\
readOnlyFullEnabled\": false,\"readWriteEnabled\": false,\"icalEnabled\"\
: false}'\n"
- lang: C#
source: "// Specify sheet publish status properties\nSheetPublish publishSpecification\
\ = new SheetPublish\n{\n ReadOnlyLiteEnabled = true,\n ReadOnlyFullEnabled\
\ = false,\n ReadWriteEnabled = false,\n IcalEnabled = false\n};\n\n//\
\ Set sheet publish status\nSheetPublish updatedStatus = smartsheet.SheetResources.UpdatePublishStatus(\n\
\ 4583614634583940, // sheetId\n publishSpecification\n);\n"
- lang: Java
source: "// Specify sheet publish status properties\nSheetPublish publishSpecification\
\ = new SheetPublish()\n .setIcalEnabled(false)\n .setReadOnlyFullEnabled(false)\n\
\ .setReadWriteEnabled(false)\n .setReadOnlyLiteEnabled(true);\n\
\n// Set sheet publish status\nSheetPublish updatedStatus = smartsheet.sheetResources().updatePublishStatus(\n\
\ 4583614634583940L, // long sheetId\n publishSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Specify publish status\nvar publishStatus = {\n \"readOnlyLiteEnabled\"\
: true,\n \"readOnlyFullEnabled\": false,\n \"readWriteEnabled\": false,\n\
\ \"icalEnabled\": false\n};\n\n// Set options\nvar options = {\n sheetId:\
\ 4583614634583940,\n body: publishStatus\n };\n\n// Set publish status\n\
smartsheet.sheets.setPublishStatus(options)\n\t.then(function(updatedStatus)\
\ {\n\t\tconsole.log(updatedStatus);\n\t})\n\t.catch(function(error) {\n\
\t\tconsole.log(error);\n\t});\n"
label: Node.js
- lang: Python
source: "# With the Python SDK, if fewer than all four flags are set, current\
\ status is retrieved and merged with the flags that _are_ set with this\
\ method call.\n\nupdated_status = smartsheet_client.Sheets.set_publish_status(\n\
\ 4583173393803140, # sheet_id\n smartsheet.models.SheetPublish({\n\
\ 'read_only_lite_enabled': True\n })\n)\n"
- lang: Ruby
source: "body = {\n read_only_lite_enabled: true,\n read_only_full_enabled:\
\ true,\n read_only_full_accessible_by: 'ALL',\n read_write_enabled: true,\n\
\ read_write_accessible_by: 'ORG',\n ical_enabled: true\n}\n\nstatus =\
\ smartsheet.sheets.set_publish_status(\n sheet_id: 4583173393803140,\n\
\ body: body\n)\n"
/sheets/{sheetId}/rows:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Add Rows
description: >
Inserts one or more rows into the sheet specified in the URL. If you
want to insert the rows in any position but the default, use
[location-specifier](../../tag/rowsRelated#section/Specify-Row-Location)
attributes.
This operation supports both single-object and bulk semantics. For more
information, see Optional Bulk Operations.
operationId: rows-addToSheet
tags:
- rows
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- name: allowPartialSuccess
in: query
description: When specified with a value of true, enables partial success
for this bulk operation. See [Partial Success]() for more information.
schema:
type: boolean
default: false
required: false
- name: overrideValidation
in: query
description: 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.
schema:
type: boolean
default: false
required: false
requestBody:
description: >
[Row object](../../tag/rowsObjects#section/Row-Object) or an array of
Row objects, with the following attributes:
* One or more [location-specifier attributes](../../tag/rowsRelated#section/Specify-Row-Location)
(optional)
* **expanded** (optional)
* **format** (optional)
* **cells** (optional) -- if specified, must be an array of [Cell objects](../../tag/cellsObjects#section/Cell-Object),
where each object is limited to the following attributes:
* **columnId** (required)
* One of the following (required):
* **formula**: the formula for the cell. For cross-sheet formulas,
you must first define a [cross-sheet reference](../../tag/crossSheetReferencesDescription)
* **value**
* When **value** is specified
* [hyperlink](../../tag/dashboardsObjects#section/WidgetHyperlink-Object)
(optional) with exactly one of the following attributes set:
* **reportId**
* **sheetId**
* **url**
* [linkInFromCell]() (optional) with all of the following attributes
set:
* **columnId**
* **rowId**
* **sheetId**
* **strict** (optional)
* **format** (optional)
* **image** (optional) -- if specified, use to update alternate text
where altText = string.
* **overrideValidation** (optional)
* **locked** (optional) - **true** to lock the row or **false** to unlock
the row.
See [Column Types](../../tag/columnsRelated#section/Column-Types) for more
information.
**NOTE:**
* Column Ids must be valid for the sheet to which the row belongs, and must
only be used once for each row in the operation.
* Cells of a project sheet in the "Finish Date" column cannot be updated
via API.
* Cells of a project sheet in the "Start Date" column cannot be updated
via API for rows that contain a value in the "Predecessor" column.
* Max length for a cell value is 4000 characters after which truncation
occurs without warning. Empty string values are converted to null.
* Calculation errors or problems with a formula 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".
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ReportRow/allOf/0'
- type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: Returns [Result object](../../tag/commonObjects#section/Result-Object)
containing the newly created rows -- either a single [Row object](../../tag/rowsObjects#section/Row-Object)
or array of Row objects, corresponding to what was specified in the request,
as well as the new version of the sheet.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: array
items:
type: object
properties:
id:
description: Row Id.
type: number
sheetId:
description: Parent sheet Id.
type: number
rowNumber:
description: Row number within the sheet.
type: number
minimum: 1
expanded:
description: Indicates whether the row is expanded or
collapsed.
type: boolean
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
cells:
description: Cells objects.
type: array
items:
type: object
properties:
columnId:
type: number
description: The Id of the column that the cell
is located in.
columnType:
type: string
description: Only returned if the include query
string parameter contains **columnType**.
value:
anyOf:
- type: string
- type: number
- type: boolean
description: 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.
displayValue:
type: string
description: Visual representation of cell contents,
as presented to the user in the UI.
version:
description: Sheet version number that is incremented
every time a sheet is modified.
type: number
default:
description: >
When **allowPartialSuccess=false** (or not specified):
If an error occurs, the [Error object](../../tag/commonObjects#section/Error-Object)
returned contains a **detail** attribute set to an object with the following
attribute:
* **index**: the array index of the row that caused the error (0 if a
single Row was passed in)
If any error occurs, the entire request fails (no rows are added), and
the error response returned describes the first problem that was encountered.
For example:
```
{
"errorCode": 1042,
"message": "The cell value in column 5504245941200772 did not conform
to the strict requirements for type CHECKBOX."
"detail": {
"index": 4
}
}
```
When **allowPartialSuccess=true**:
When partial success is enabled, and one or more of the objects in the
request fail to be added/updated/deleted, a standard [Result object](../../tag/commonObjects#section/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](../../tag/commonObjects#section/BulkItemFailure-Object)
that contains an item for each object in the request that failed to be
added/updated/deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows \\\n-H\
\ \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{\"toTop\":true, \"cells\": [\
\ {\"columnId\": 7960873114331012, \"value\": true}, {\"columnId\": 642523719853956,\
\ \"value\": \"New status\", \"strict\": false} ] }, {\"toTop\":true, \"\
cells\": [ {\"columnId\": 7960873114331012, \"value\": true}, {\"columnId\"\
: 642523719853956, \"value\": \"New status\", \"strict\": false} ] }]'\n"
- lang: C#
source: "// Specify cell values for first row\nCell[] cellsToInsert = new\
\ Cell[]\n{\n new Cell\n {\n ColumnId = addedColumns[0].Id,\n ObjectValue\
\ = new MultiPicklistObjectValue(new string[] {\"Bat\", \"Cat\"})\n }\n\
};\nRow rowA = new Row\n{\n ToTop = true,\n Cells = cellsToInsert\n};\n\
\n// Specify cell values of second row\nCell[] cellsB = new Cell[] {\n \
\ new Cell\n {\n ColumnId = 7960873114331012,\n Value = true\n },\n\
\ new Cell\n {\n ColumnId = 642523719853956,\n Value = \"New status\"\
\n }\n};\n\n// Specify contents of second row\nRow rowB = new Row\n{\n\
\ ToTop = true,\n Cells = cellsB\n};\n\n// Add rows to sheet\nIList\
\ newRows = smartsheet.SheetResources.RowResources.AddRows(\n 2331373580117892,\
\ // sheetId\n new Row[] { rowA, rowB } // IEnumerable\
\ rowsToAdd\n);\n"
- lang: Java
source: "// Specify cell values for first row\nList rowACells = Arrays.asList(\n\
\ new Cell(7960873114331012L) // column Id\n .setValue(true),\n\
\ new Cell(642523719853956L) // column Id\n .setValue(\"\
New status\")\n );\n\n// Specify contents of first row\nRow rowA\
\ = new Row();\nrowA.setCells(rowACells)\n .setToBottom(true);\n\n\
// Specify cell values for second row\nList rowBCells = Arrays.asList(\n\
\ new Cell(7960873114331012L)\n .setValue(true),\n \
\ new Cell(642523719853956L)\n .setValue(\"New status\")\n \
\ );\n\n// Specify contents of second row\nRow rowB = new Row();\nrowB.setCells(rowBCells)\n\
\ .setToBottom(true);\n\n// Add rows to sheet\nList newRows\
\ = smartsheet.sheetResources().rowResources().addRows(\n 1639534409607044L,\
\ // sheet Id\n Arrays.asList(rowA, rowB));\n"
- lang: JavaScript
source: "// Specify rows\nvar row = [\n {\n \"toTop\": true,\n \"cells\"\
: [\n {\n \"columnId\": 7960873114331012,\n \"value\"\
: true\n },\n {\n \"columnId\": 642523719853956,\n \
\ \"value\": \"New status\",\n \"strict\": false\n }\n \
\ ]\n },\n {\n \"toTop\": true,\n \"cells\": [\n {\n \
\ \"columnId\": 7960873114331012,\n \"value\": true\n },\n\
\ {\n \"columnId\": 642523719853956,\n \"value\": \"\
New status\",\n \"strict\": false\n }\n ]\n }\n];\n\n//\
\ Set options\nvar options = {\n sheetId: 2252168947361668,\n body: row\n\
\ };\n\n// Add rows to sheet\nsmartsheet.sheets.addRows(options)\n .then(function(newRows)\
\ {\n console.log(newRows);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "# Specify cell values for one row\nrow_a = smartsheet.models.Row()\n\
row_a.to_top = True\nrow_a.cells.append({\n 'column_id': 7960873114331012,\n\
\ 'value': True\n})\nrow_a.cells.append({\n 'column_id': 642523719853956\n\
\ 'value': 'New Status',\n 'strict': False\n})\n\n# Specify cell values\
\ for another row\nrow_b = smartsheet.models.Row()\nrow_b.to_top = True\n\
row_b.cells.append({\n 'column_id': 7960873114331012,\n 'value': True\n\
})\nrow_b.cells.append({\n 'column_id': 642523719853956\n 'value': 'New\
\ Status',\n 'strict': False\n})\n\n# Add rows to sheet\nresponse = smartsheet_client.Sheets.add_rows(\n\
\ 2331373580117892, # sheet_id\n [row_a, row_b])\n"
- lang: Ruby
source: "# Specify values\nbody = {\n to_bottom: true,\n cells: [\n {\n\
\ column_id: 495660408563588,\n value: 'New Status'\n }\n \
\ ],\n locked: false\n}\n\n# Add rows to a sheet\nresponse = smartsheet.sheets.rows.add(\n\
\ sheet_id: 2331373580117892,\n body: body\n)\n"
delete:
summary: Delete Rows
description: Deletes one or more rows from the sheet specified in the URL.
operationId: delete-rows
tags:
- rows
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- name: ids
in: query
required: true
description: |
A comma-separated list of row Ids.
schema:
type: string
- name: ignoreRowsNotFound
description: >
**true** or **false**. If set to **false** and any of the specified
row Ids are not found, no rows are deleted, and the "not found"
[error](../../tag/commonObjects#section/Error-Object) is returned.
in: query
required: false
schema:
type: boolean
default: false
responses:
'200':
description: Returns [Result object](../../tag/commonObjects#section/Result-Object)
containing row Ids corresponding to all rows that were successfully deleted
(including any child rows of rows specified in the URL).
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
type: number
'404':
$ref: '#/paths/~1contacts/get/responses/404'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows?ids={rowId1},{rowId2},{rowId3}&ignoreRowsNotFound=true'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "// Specify 'ignoreRowsNotFound' parameter with value of 'true'\n\
smartsheet.SheetResources.RowResources.DeleteRows(\n 2252168947361668,\
\ // sheetId\n new long[] { 207098194749316,\
\ 207098194749317 }, // rowIds\n true \
\ // Boolean ignoreRowsNotFound\n);\n"
- lang: Java
source: "// Specify 'ignoreRowsNotFound' parameter with value of 'true'\n\
smartsheet.sheetResources().rowResources().deleteRows(\n 2252168947361668L,\
\ // long sheetId\n new HashSet(Arrays.asList(\n \
\ 207098194749316L, // long rowId,\n 207098194749317L,\
\ // long additional rowId\n 207098194749318L,) \
\ // long additional rowId\n true \
\ // Boolean ignoreRowsNotFound\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ rowId: 207098194749316\n};\n\n// Delete row\nsmartsheet.sheets.deleteRow(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.delete_rows(\n 2252168947361668, \
\ # sheet_id\n [207098194749316, 207098194749317]) \
\ # row_ids\n"
- lang: Ruby
source: "smartsheet.sheets.rows.delete(\n sheet_id: 2252168947361668,\n \
\ row_ids: [207098194749316, 207098194749316]\n)\n"
put:
summary: Update Rows
description: Updates cell values in the specified rows, expands/collapses the
specified rows, or modifies the position of specified rows (including indenting/outdenting).
For detailed information about changing row positions, see [location-specifier
attributes](../../tag/rowsRelated#section/Specify-Row-Location).
operationId: update-rows
tags:
- rows
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/parameters/1'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/parameters/2'
requestBody:
description: >
[Row object](../../tag/rowsObjects#section/Row-Object) or an array of
Row objects, with the following attributes:
* **id** (required)
* One or more [location-specifier attributes](../../tag/rowsRelated#section/Specify-Row-Location)
(optional)
* **expanded** (optional)
* **format** (optional)
* **cells** (optional) -- if specified, must be an array of [Cell objects](),
where each object is limited to the following attributes:
* **columnId** (required)
* One of the following (required):
* **formula**: the formula for the cell. For cross-sheet formulas,
you must first define a [cross-sheet reference](../../tag/crossSheetReferencesDescription)
* **value**
* When **value** is specified
* [hyperlink](../../tag/dashboardsObjects#section/WidgetHyperlink-Object)
(optional) with exactly one of the following attributes set:
* **reportId**
* **sheetId**
* **url**
* [linkInFromCell]() (optional) with all of the following attributes
set:
* **columnId**
* **rowId**
* **sheetId**
* **strict** (optional)
* **format** (optional)
* **image** (optional) -- if specified, use to update alternate text
where altText = string.
* **overrideValidation** (optional)
* **locked** (optional) - **true** to lock the row or **false** to unlock
the row.
See [Column Types](../../tag/columnsRelated#section/Column-Types) for more
information.
**NOTE:**
* Column Ids must be valid for the sheet to which the row belongs, and must
only be used once for each row in the operation.
* Cells of a project sheet in the "Finish Date" column cannot be updated
via API.
* Cells of a project sheet in the "Start Date" column cannot be updated
via API for rows that contain a value in the "Predecessor" column.
* Max length for a cell value is 4000 characters after which truncation
occurs without warning. Empty string values are converted to null.
* Calculation errors or problems with a formula 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".
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/requestBody/content/application~1json/schema/oneOf/0'
- type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: Returns [Result object](../../tag/commonObjects#section/Result-Object)
containing an array of the updated rows.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
type: object
properties:
id:
description: Row Id.
type: number
rowNumber:
description: Row number within the sheet.
type: number
minimum: 1
parentRowNumber:
description: The row number of the parent.
type: number
parentId:
description: The Id of the parent.
type: number
expanded:
description: Indicates whether the row is expanded or
collapsed.
type: boolean
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
cells:
description: Cells objects.
type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/responses/200/content/application~1json/schema/allOf/1/properties/result/items/properties/cells/items'
version:
description: Sheet version number that is incremented
every time a sheet is modified.
type: number
default:
description: >
When **allowPartialSuccess=false** (or not specified):
If an error occurs, the [Error object](../../tag/commonObjects#section/Error-Object)
returned contains a **detail** attribute set to an object with the following
attribute:
* **index**: the array index of the row that caused the error (0 if a
single Row was passed in)
* **rowId**: the id of the row that caused the error (omitted if the row
was missing an Id)
If any error occurs, the entire request fails (no rows are added), and
the error response returned describes the first problem that was encountered.
For example:
```
{
"errorCode": 1042,
"message": "The cell value in column 5504245941200772 did not conform
to the strict requirements for type CHECKBOX."
"detail": {
"index": 4
"rowId": 6572427401553796
}
}
```
When **allowPartialSuccess=true**:
When partial success is enabled, and one or more of the objects in the
request fail to be added/updated/deleted, a standard [Result object](../../tag/commonObjects#section/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](../../tag/commonObjects#section/BulkItemFailure-Object)
that contains an item for each object in the request that failed to be
added/updated/deleted.
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "<<<<<<< HEAD\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '[{\"id\": \"6572427401553796\",\
\ \"cells\": [{\"columnId\": 7518312134403972,\"image\": {\"altText\": \"\
New Alt Text\"},\"value\": \"new value\"}, {\"columnId\": 1888812600190852,\"\
value\": \"A\"}]}, {\"id\": \"2068827774183300\", \"cells\": [{\"columnId\"\
: 7518312134403972,\"value\": \"desc_updated\"}, {\"columnId\": 1888812600190852,\"\
value\": \"B\"}, {\"columnId\": 6552023773538180,\"objectValue\": {\"objectType\"\
: \"MULTI_CONTACT\",\"values\": [{\"objectType\": \"CONTACT\",\"email\"\
: \"john.doe@smartsheet.com\",\"name\": \"John Doe\"}, {\"objectType\":\
\ \"CONTACT\",\"email\": \"jane.roe@smartsheet.com\",\"name\": \"Jane Roe\"\
}]}}]}]'\n=======\ncurl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows?include=objectValue'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '[{\"id\": \"6572427401553796\",\
\ \"cells\": [{\"columnId\": 7518312134403972,\"objectValue\": {\"objectType\"\
: \"PREDECESSOR_LIST\",\"predecessors\": [{\"rowId\": 567735454328708,\"\
type\": \"FS\",\"lag\": {\"objectType\": \"DURATION\",\"days\": 2,\"hours\"\
: 4}}]}}]}]'\n>>>>>>> develop\n"
- lang: C#
source: "// Specify updated value for first cell\nvar cellToUpdateA = new\
\ Cell\n{\n ColumnId = 7518312134403972,\n Value = \"new value\"\n};\n\
\n// Specify updated value for second cell\nvar cellToUpdateB = new Cell\n\
{\n ColumnId = 1888812600190852,\n Value = \"A\"\n};\n\n// Identify row\
\ and add new cell values to it\nvar rowToUpdate = new Row\n{\n Id = 6572427401553796,\n\
\ Cells = new Cell[] { cellToUpdateA, cellToUpdateB }\n};\n\nIList\
\ updatedRow = smartsheet.SheetResources.RowResources.UpdateRows(\n 2068827774183300,\
\ // sheet Id\n new Row[] {rowToUpdate}\n);\n"
- lang: Java
source: "// Specify updated cell values for first row\nCell cellA = new Cell(7518312134403972L)\
\ // column Id\n .setValue(\"new value\");\n\nCell cellB = new\
\ Cell(6392412227561348L) // column Id\n .setValue(123);\n\nRow\
\ rowA = new Row(2068827774183300L);\n rowA.setCells(Arrays.asList(cellA,\
\ cellB));\n\n// Specify updated cell values for second row\nCell cellC\
\ = new Cell(7518312134403972L)\n .setValue(\"desc_updated\");\n\n\
Cell cellD = new Cell(6392412227561348L)\n .setValue(456);\n\nRow\
\ rowB = new Row(6572427401553796L);\n rowB.setCells(Arrays.asList(cellC,\
\ cellD));\n\n// Update rows in sheet\nList updatedRows = smartsheet.sheetResources().rowResources().updateRows(\n\
\ 1639534409607044L, // long sheetId\n \
\ Arrays.asList(rowA, rowB)\n );\n"
- lang: JavaScript
source: "// Specify updated cell values\nvar row = [\n {\n \"id\": \"\
6572427401553796\",\n \"cells\": [\n {\n \"columnId\": 7518312134403972,\n\
\ \"value\": \"new value\"\n },\n {\n \"columnId\"\
: 1888812600190852,\n \"value\": \"A\"\n }\n ]\n },\n {\n\
\ \"id\": \"2068827774183300\",\n \"cells\": [\n {\n \"\
columnId\": 7518312134403972,\n \"value\": \"desc_updated\"\n \
\ },\n {\n \"columnId\": 1888812600190852,\n \"value\"\
: \"B\"\n }\n ]\n }\n];\n\n// Set options\nvar options = {\n sheetId:\
\ 2068827774183300,\n body: row\n };\n\n// Update rows in sheet\nsmartsheet.sheets.updateRow(options)\n\
\ .then(function(updatedRows) {\n console.log(updatedRows);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Build new cell value\nnew_cell = smartsheet.models.Cell()\nnew_cell.column_id\
\ = 7036894123976580\nnew_cell.value = \"new value\"\nnew_cell.strict =\
\ False\n\n# Build the row to update\nnew_row = smartsheet.models.Row()\n\
new_row.id = 6809535313667972\nnew_row.cells.append(new_cell)\n\n# Update\
\ rows\nupdated_row = smartsheet_client.Sheets.update_rows(\n 2068827774183300,\
\ # sheet_id\n [new_row])\n"
- lang: Ruby
source: "# Specify updated cell values\nbody = {\n id: 4293147074291588,\
\ # row Id\n cells: [\n column_id: 7036894123976580,\n value: 'new\
\ value'\n ]\n}\n\n# Update row\nresponse = smartsheet.sheets.rows.update(\n\
\ sheet_id: 2068827774183300,\n body: body\n)\n"
/sheets/{sheetId}/rows/emails:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Send Rows via Email
description: Sends one or more rows via email.
operationId: rows-send
tags:
- rows
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
description: >
The columns included for each row in the email are populated according
to the following rules:
* If the **columnIds** attribute of the MultiRowEmail object is specified
as an array of column Ids, those specific columns are included.
* If the **columnIds** attribute of the MultiRowEmail object is omitted,
all columns except hidden columns shall be included.
* If the **columnIds** attribute of the MultiRowEmail object is specified
as empty, no columns shall be included. (**NOTE:** In this case, either
**includeAttachments=true** or **includeDiscussions=true** must be specified.)
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRequest/allOf/0'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/emails\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\n \"sendTo\": [\n {\"email\"\
: \"recipient@smartsheet.com\"}\n ],\n \"subject\": \"Check these rows\
\ out!\",\n \"message\": \"Here are the rows I mentioned in our meeting\"\
,\n \"ccMe\": false,\n \"rowIds\": [\n 6327127650920324, 3404239197235076\n\
\ ],\n \"columnIds\": [\n 5190835902932868, 3791509922310020\n ],\n\
\ \"includeAttachments\": false,\n \"includeDiscussions\": false\n}\n"
- lang: C#
source: "// Specify recipients\nRecipient[] recipients = new Recipient[] {\n\
\ new Recipient { Email = \"recipient@smartsheet.com\" }\n};\n\n// Configure\
\ email\nMultiRowEmail multiRowEmail = new MultiRowEmail {\n SendTo = recipients,\n\
\ Subject = \"some subject\",\n Message = \"some message\",\n CcMe =\
\ false,\n RowIds = new long[] { 6327127650920324, 3404239197235076 },\n\
\ ColumnIds = new long[] { 5190835902932868, 3791509922310020 },\n IncludeAttachments\
\ = false,\n IncludeDiscussions = false\n};\n\n// Send rows via email\n\
smartsheet.SheetResources.RowResources.SendRows(4293147074291588, multiRowEmail);\
\ // sheetId\n"
- lang: Java
source: "// Specify recipients\nRecipientEmail recipientEmail = new RecipientEmail.AddRecipientEmailBuilder()\n\
\ .setEmail(\"recipient@smartsheet.com\")\n .build();\n\n\
List recipients = new ArrayList();\nrecipients.add(recipientEmail);\n\
\n// Configure email\nMultiRowEmail multiRowEmail = new MultiRowEmail.AddMultiRowEmailBuilder()\n\
\ .setSendTo(recipients)\n .setSubject(\"some subject\")\n\
\ .setMessage(\"some message\")\n .setCcMe(false)\n \
\ .setRowIds(Arrays.asList(6327127650920324L, 3404239197235076L)\n \
\ .setColumnIds(Arrays.asList(5190835902932868L, 3791509922310020L)\n\
\ .setIncludeAttachments(false)\n .setIncludeDiscussions(false)\n\
\ .build();\n\n// Send rows via email\nsmartsheet.sheetResources().rowResources().sendRows(4293147074291588L,\
\ multiRowEmail); // sheetId\n"
- lang: JavaScript
source: "// Configure email\nvar email = {\n \"sendTo\": [\n {\n \
\ \"email\": \"john.doe@smartsheet.com\"\n },\n {\n \"groupId\"\
: 2258118617917316\n }\n ],\n \"subject\": \"Check these rows out!\"\
,\n \"message\": \"Here are the rows I mentioned in our meeting\",\n \"\
ccMe\": false,\n \"includeDiscussions\": false,\n \"includeAttachments\"\
: true,\n \"rowIds\": [\n 1049041315358596,\n 5552640942729092\n\
\ ]\n};\n\n// Set options\nvar options = {\n \"body\": email,\n \"sheetId\"\
: 2252168947361668\n};\n\n// Send row via email\nsmartsheet.sheets.sendRows(options)\n\
\ .then(function(data) {\n console.log(data);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Configure email\nemail = smartsheet.models.MultiRowEmail()\nemail.send_to\
\ = smartsheet.models.Recipient({\n 'email': 'john.doe@smartsheet.com'\n\
})\nemail.row_ids = [6327127650920324, 3404239197235076]\nemail.column_ids\
\ = [5190835902932868, 3791509922310020]\n\n# Send rows via email\nresponse\
\ = smartsheet_client.Sheets.send_rows(\n 4293147074291588, # sheet_id\n\
\ email)\n"
- lang: Ruby
source: "# Configure email\nbody = {\n row_ids: [\n 409840559384452,\n\
\ 2661640373069700\n ],\n column_ids: [\n 495660408563588,\n \
\ 2747460222248836\n ],\n send_to: [\n {\n email: 'john.doe@smartsheet.com'\n\
\ },\n {\n group_id: 3051008235464580\n }\n ],\n subject:\
\ 'Check these rows out!',\n message: 'Here are the rows I mentioned in\
\ our meeting',\n cc_me: false,\n include_attachments: false,\n include_discussions:\
\ true,\n layout: 'VERTICAL'\n}\n\n# Send rows\nresponse = smartsheet.sheets.rows.send_via_email(\n\
\ sheet_id: 4583173393803140,\n body: body\n)\n"
/sheets/{sheetId}/rows/copy:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Copy Rows to Another Sheet
description: Copies rows from the sheet specified in the URL to (the bottom
of) another sheet.
operationId: copy-rows
tags:
- rows
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- name: include
in: query
required: false
description: >
A comma-separated list of row elements to copy in addition to the
cell data:
* **all** - specify a value of **all** to include everything (attachments,
children, and discussions).
* **attachments**
* **children** - if specified, any child rows of the rows specified in
the request are also copied to the destination sheet, and parent-child relationships
amongst rows are preserved within the destination sheet; if not specified,
only the rows specified in the request are copied.
* **discussions**
schema:
type: string
enum:
- all
- attachments
- children
- discussions
- name: ignoreRowsNotFound
description: >
**true** or **false**: default is **false**. If set to **true**,
specifying row Ids that do not exist within the source sheet does
not cause an error response. If omitted or set to **false**,
specifying row Ids that do not exist within the source sheet causes
an error response (and no rows are copied).
in: query
required: false
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
type: object
properties:
rowIds:
description: The Ids of the rows to move or copy from the source
sheet.
type: array
items:
type: number
to:
$ref: '#/components/schemas/CopyOrMoveRowDirective/properties/to'
responses:
'200':
description: CopyOrMoveRowResult object
content:
application/json:
schema:
type: object
properties:
destinationSheetId:
description: The Id of the destination sheet.
type: number
rowMappings:
description: Array of rowMapping objects.
type: array
items:
$ref: '#/components/schemas/CopyOrMoveRowResult/properties/rowMappings/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/copy \\\
\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{ \"rowIds\": [145417762563972,\
\ 8026717110462340], \"to\": {\"sheetId\": 2258256056870788} }'\n"
- lang: C#
source: "// Specify destination sheet\nCopyOrMoveRowDestination destination\
\ = new CopyOrMoveRowDestination { SheetId = 2258256056870788 };\n\n// Specify\
\ rows to be copied (and destination sheet)\nCopyOrMoveRowDirective directive\
\ = new CopyOrMoveRowDirective { RowIds = new long[] { 145417762563972,\
\ 8026717110462340 }, To = destination };\n\n// Sample 1: Omit 'include'\
\ and 'ignoreRowsNotFound' parameters\nCopyOrMoveRowResult results = smartsheet.SheetResources.RowResources.CopyRowsToAnotherSheet(\n\
\ 4583173393803140, // sheetId\n directive,\n null, \
\ // IEnumerable include\n null \
\ // Nullable ignoreRowsNotFound\n);\n\n// Sample\
\ 2: Specify 'include' parameter with value of \"CHILDREN\", and 'ignoreRowsNotFound'\
\ parameter with value of 'true'\nCopyOrMoveRowResult results = smartsheet.SheetResources.RowResources.CopyRowsToAnotherSheet(\n\
\ 4583173393803140, // sheetId\n directive,\n new CopyRowInclusion[]\
\ {\n CopyRowInclusion.CHILDREN },\n true\n);\n"
- lang: Java
source: "// Specify destination sheet\nCopyOrMoveRowDestination destination\
\ = new CopyOrMoveRowDestination()\n .setSheetId(2258256056870788L);\n\
\n// Specify rows to be copied (and destination sheet)\nCopyOrMoveRowDirective\
\ directive = new CopyOrMoveRowDirective()\n .setRowIds(Arrays.asList(145417762563972L,\
\ 8026717110462340L))\n .setTo(destination);\n\n// Sample 1: Omit\
\ 'include' and 'ignoreRowsNotFound' parameters\nCopyOrMoveRowResult results\
\ = smartsheet.sheetResources().rowResources().copyRows(\n 4583173393803140L,\
\ // long sheetId\n null, \
\ // EnumSet includes\n true,\
\ // Boolean ignoreRowsNotFound\n \
\ directive\n );\n\n// Sample 2: Specify 'include' parameter\
\ with value of \"CHILDREN\", and 'ignoreRowsNotFound' parameter with value\
\ of 'true'\nCopyOrMoveRowResult results = smartsheet.sheetResources().rowResources().copyRows(\n\
\ 4583173393803140L, // long sheetId\n \
\ EnumSet.of(RowCopyInclusion.CHILDREN),\n true,\n directive\n\
\ );\n"
- lang: JavaScript
source: "// Specify the directive\nvar copyRow = {\n \"rowIds\": [145417762563972,8026717110462340],\n\
\ \"to\": {\n \"sheetId\": 2258256056870788\n }\n};\n\n// Set options\n\
var options = {\n sheetId: 4583173393803140,\n body: copyRow\n };\n\n\
// Copy rows\nsmartsheet.sheets.copyRowToAnotherSheet(options)\n .then(function(results)\
\ {\n console.log(results);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.copy_rows(\n 4583173393803140,\
\ # sheet_id of rows to be copied\n smartsheet.models.CopyOrMoveRowDirective({\n\
\ 'row_ids': [145417762563972, 8026717110462340],\n 'to': smartsheet.models.CopyOrMoveRowDestination({\n\
\ 'sheet_id': 2258256056870788\n })\n })\n)\n"
- lang: Ruby
source: "# Specify rows to copy and destination sheet\nbody = {\n row_ids:\
\ [\n 145417762563972,\n 8026717110462340\n ],\n to: {\n sheet_id:\
\ 2258256056870788\n }\n}\n\n# Copy rows to another sheet\nresponse = smartsheet.sheets.rows.copy_to_another_sheet(\n\
\ sheet_id: 4583173393803140,\n body: body\n)\n"
/sheets/{sheetId}/rows/move:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Move Rows to Another Sheet
description: Moves rows from the sheet specified in the URL to (the bottom of)
another sheet.
operationId: move-rows
tags:
- rows
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- name: include
in: query
required: false
description: >
A comma-separate list of row elements to move in addition to the
cell data.
schema:
type: string
enum:
- attachments
- discussions
- name: ignoreRowsNotFound
description: >
**true** or **false**: default is **false**. If set to **true**,
specifying row Ids that do not exist within the source sheet does
not cause an error response. If omitted or set to **false**,
specifying row Ids that do not exist within the source sheet causes
an error response (and no rows are moved).
in: query
required: false
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1copy/post/requestBody/content/application~1json/schema'
responses:
'200':
description: CopyOrMoveRowResult object
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1copy/post/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/move \\\
\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{ \"rowIds\": [145417762563972,\
\ 8026717110462340], \"to\": {\"sheetId\": 2258256056870788} }'\n"
- lang: C#
source: "// Specify destination sheet\nCopyOrMoveRowDestination destination\
\ = new CopyOrMoveRowDestination { SheetId = 2258256056870788 };\n\n// Specify\
\ rows to be moved (and destination sheet)\nCopyOrMoveRowDirective directive\
\ = new CopyOrMoveRowDirective { RowIds = new long[] { 145417762563972,\
\ 8026717110462340 }, To = destination };\n\n// Sample 1: Omit 'include'\
\ and 'ignoreRowsNotFound' parameters\nCopyOrMoveRowResult results = smartsheet.SheetResources.RowResources.MoveRowsToAnotherSheet(\n\
\ 4583173393803140, // sheetId\n directive,\n null, \
\ // IEnumerable include\n null\
\ // Nullable ignoreRowsNotFound\n);\n\n\
// Sample 2: Specify 'include' parameter with value of \"ATTACHMENTS\" and\
\ \"DISCUSSIONS\", and 'ignoreRowsNotFound' parameter with value of 'true'\n\
CopyOrMoveRowResult results = smartsheet.SheetResources.RowResources.MoveRowsToAnotherSheet(\n\
\ 4583173393803140, // sheetId\n directive,\n new MoveRowInclusion[]\
\ {\n MoveRowInclusion.ATTACHMENTS,\n MoveRowInclusion.DISCUSSIONS\
\ },\n true // Nullable ignoreRowsNotFound\n\
);\n"
- lang: Java
source: "// Specify destination sheet\nCopyOrMoveRowDestination destination\
\ = new CopyOrMoveRowDestination()\n .setSheetId(2258256056870788L);\n\
\n// Specify rows to be moved (and destination sheet)\nCopyOrMoveRowDirective\
\ directive = new CopyOrMoveRowDirective()\n .setRowIds(Arrays.asList(145417762563972L,\
\ 8026717110462340L))\n .setTo(destination);\n\n// Sample 1: Omit\
\ 'include' and 'ignoreRowsNotFound' parameters\nCopyOrMoveRowResult results\
\ = smartsheet.sheetResources().rowResources().moveRows(\n 4583173393803140L,\
\ // long sheetId\n null, \
\ // EnumSet includes\n true, \
\ // Boolean ignoreRowsNotFound\n directive\n\
\ );\n\n// Sample 2: Specify 'include' parameter with value of \"\
ATTACHMENTS\" and \"DISCUSSIONS\", and 'ignoreRowsNotFound' parameter with\
\ value of 'true'\nCopyOrMoveRowResult results = smartsheet.sheetResources().rowResources().moveRows(\n\
\ 4583173393803140L, // long sheetId\n EnumSet.of(\n\
\ RowMoveInclusion.ATTACHMENTS,\n RowMoveInclusion.DISCUSSIONS),\n\
\ true, // Boolean ignoreRowsNotFound\n\
\ directive\n );\n"
- lang: JavaScript
source: "// Specify the directive\nvar moveRow = {\n \"rowIds\": [145417762563972,8026717110462340],\n\
\ \"to\": {\n \"sheetId\": 2258256056870788\n }\n};\n\n// Set options\n\
var options = {\n sheetId: 4583173393803140,\n body: moveRow\n };\n\n\
// Move rows\nsmartsheet.sheets.moveRowToAnotherSheet(options)\n .then(function(movedRow)\
\ {\n console.log(movedRow);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.move_rows(\n 4583173393803140,\
\ # sheet_id of rows to be moved\n smartsheet.models.CopyOrMoveRowDirective({\n\
\ 'row_ids': [145417762563972, 8026717110462340],\n 'to': smartsheet.models.CopyOrMoveRowDestination({\n\
\ 'sheet_id': 2258256056870788\n })\n })\n)\n"
- lang: Ruby
source: "# Specify rows to move and destination sheet\nbody = {\n row_ids:\
\ [\n 145417762563972,\n 8026717110462340\n ],\n to: {\n sheet_id:\
\ 2258256056870788\n }\n}\n\n# Move rows to another sheet\nresponse = smartsheet.sheets.rows.move_to_another_sheet(\n\
\ sheet_id: 4583173393803140,\n body: body\n)\n"
/sheets/{sheetId}/rows/{rowId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: rowId
in: path
schema:
type: number
required: true
description: Row Id in the sheet being accessed.
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Row
description: Gets the row specified in the URL.
operationId: row-get
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of elements to include in the response.
See [Row Include Flags](../../tag/rowsRelated#section/Row-Include-Flags).
Also supports the **columns** include flag, which adds a columns array that
specifies all of the columns for the sheet. This enables you to have the
full context of the cells in the row.
The **filters** include flag returns a **filteredOut** attribute indicating
if the row should be displayed or hidden according to the sheet's filters.
schema:
type: string
enum:
- columns
- filters
- $ref: '#/paths/~1sheets~1%7BsheetId%7D/get/parameters/2'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D/get/parameters/6'
tags:
- rows
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: Returns [Row object]() populated according to the specified
parameters.
content:
application/json:
schema:
allOf:
- type: object
properties:
id:
description: Row Id.
type: number
sheetId:
description: Parent sheet Id.
type: number
rowNumber:
description: Row number within the sheet.
type: number
minimum: 1
expanded:
description: Indicates whether the row is expanded or collapsed.
type: boolean
cells:
description: Cells objects.
type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/responses/200/content/application~1json/schema/allOf/1/properties/result/items/properties/cells/items'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
x-codeSamples:
- lang: cURL
source: "<<<<<<< HEAD\ncurl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}?include=discussions,attachments,columns,columnType'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n=======\n\
// Steps 1 and 2: Locate the cell and obtain the imageId\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n\n// In\
\ the response, note the columnId and ImageId\n// You might also save the\
\ altText for Step 4\n{\n\t\"cells\": [{\n\t\t\"columnId\": 6800865311909764,\n\
\t\t\"image\": {\n\t\t\t\"id\": \"nQCn-Bm2ncwqsw_FX1XI_w\",\n\t\t\t\"height\"\
: 932,\n\t\t\t\"width\": 1562,\n\t\t\t\"altText\": \"stanley hotel.png\"\
\n\t\t}\n\t}]\n}\n\n// Step 3: Obtain a temporary image URL\ncurl https://api.smartsheet.com/2.0/imageurls\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{\"imageId\": \"nQCn-Bm2ncwqsw_FX1XI_w\"\
,\"height\":40,\"width\": 20}]'\n\n// In the response, note the URL and\
\ its expiration time\n{\n \"urlExpiresInMillis\": 1800000,\n \"imageUrls\"\
: [\n {\n \"imageId\": \"nQCn-Bm2ncwqsw_FX1XI_w\",\n \"url\"\
: \"https://aws.smartsheet.com/storageProxy/image/images/OMB9hAConFbhUdJMQ5czQEkwAj1-ErW-sXz3Dr4nDfE?expirationDate=2017-07-25T22%3A13%3A07%2B0000&height=40&width=20&hmac=e%2BfIb0ffUK%2BZeA2hbGx%2Fj8YcWUY%3D\"\
\n }\n ]\n}\n\n// Step 4: Download the image\ncurl -o \"stanley_hotel.png\"\
\ \"https://aws.smartsheet.com/storageProxy/image/images/OMB9hAConFbhUdJMQ5czQEkwAj1-ErW-sXz3Dr4nDfE?expirationDate=2017-07-25T22%3A01%3A33%2B0000&height=40&width=20&hmac=5t%2FHs9%2BXTk5cNhyDax9ZgcbepKI%3D\"\
\n>>>>>>> develop\n"
- lang: C#
source: "<<<<<<< HEAD\n// Omit 'include' parameter and pagination parameters\n\
Row row = smartsheet.SheetResources.RowResources.GetRow(\n 4583173393803140,\
\ // sheetId\n 2361756178769796, // rowId\n\
\ null, // IEnumerable include\n\
\ null // IEnumerable exclude\n\
);\n\n// Specify 'include' parameter with values of \"COLUMNS\" and \"COLUMN_TYPE\"\
, and 'exclude' parameter with value of \"NONEXISTENT_CELLS\"\nRow row =\
\ smartsheet.SheetResources.RowResources.GetRow(\n 4583173393803140, \
\ // sheetId\n 2361756178769796, // rowId\n \
\ new RowInclusion[] {\n RowInclusion.COLUMNS,\n RowInclusion.COLUMN_TYPE\
\ },\n new ObjectExclusion[] { ObjectExclusion.NONEXISTENT_CELLS }\n);\n\
=======\nsheetId = 1639534409607044;\nrowId = 3344087179913092;\ncolumnId\
\ = 1735559124150148;\n\n// Step 1: Identify the cell that contains an\
\ image\nRow row = smartsheet.SheetResources.RowResources.GetRow(\n sheetId,\n\
\ rowId,\n null,\n null);\nCell cell = row.Cells.First(c => c.ColumnId\
\ == columnId);\n\n// Step 2: Get image info from cell\nImage image = cell.Image;\n\
string imageId = image.Id;\nstring localFileName = image.AltText;\n\n//\
\ Step 3: Build list of image urls\nImageUrl[] imageUrls = new ImageUrl[]\
\ { new ImageUrl { ImageId = imageId } };\n\nstring temporaryUrl = smartsheet.ImageUrlResources.GetImageUrls(imageUrls).ImageUrls[0].Url;\n\
\n// Step 4: Download the image\nSystem.Net.WebClient client = new System.Net.WebClient();\n\
client.DownloadFile(temporaryUrl, localFileName);\n>>>>>>> develop\n"
- lang: Java
source: "<<<<<<< HEAD\n// Sample 1: Omit 'include' parameter and pagination\
\ parameters\nRow row = smartsheet.sheetResources().rowResources().getRow(\n\
\ 4583173393803140L, // long sheetId\n 2361756178769796L,\
\ // long rowId\n null, // EnumSet\
\ includes\n null // EnumSet\
\ excludes\n );\n\n// Sample 2: Specify 'include' parameter with\
\ values of \"COLUMNS\" and \"COLUMN_TYPE\", and 'exclude' parameter with\
\ value of \"NONEXISTENT_CELLS\"\nRow row = smartsheet.sheetResources().rowResources().getRow(\n\
\ 4583173393803140L, // long sheetId\n 2361756178769796L,\
\ // long rowId\n EnumSet.of(\n RowInclusion.COLUMNS,\n\
\ RowInclusion.COLUMN_TYPE),\n EnumSet.of(\n ObjectExclusion.NONEXISTENT_CELLS)\n\
\ );\n=======\nlong sheetId = 5670346721388420L;\n long rowId\
\ = 3344087179913092L;\n long columnId = 1735559124150148L;\n\n//\
\ Step 1: Identify the cell that contains an image\n Row row = smartsheet.sheetResources().rowResources().getRow(\n\
\ sheetId,\n rowId,\n null,\n null);\n \
\ Cell cell = row.getCells().stream().filter(c -> c.getColumnId() == columnId).findFirst().orElse(null);\n\
\n// Step 2: Get image info from cell\n Image image = cell.getImage();\n\
\ String imageId = image.getId();\n String localFileName =\
\ image.getAltText();\n\n// Step 3: Build list of image urls\n ImageUrl\
\ imageUrl = new ImageUrl();\n imageUrl.setImageId(imageId);\n \
\ List imageUrls = Arrays.asList(imageUrl);\n\n String\
\ temporaryUrl = smartsheet.imageUrlResources().getImageUrls(imageUrls).getImageUrls().get(0).getUrl();\n\
\n// Step 4: Download the image\n CloseableHttpClient httpclient\
\ = HttpClients.createDefault();\n HttpGet httpget = new HttpGet(temporaryUrl);\n\
\ CloseableHttpResponse response = httpclient.execute(httpget);\n\
\ HttpEntity entity = response.getEntity();\n FileOutputStream\
\ fos = new FileOutputStream(localFileName);\n entity.writeTo(fos);\n\
\ fos.close();\n>>>>>>> develop\n"
- lang: JavaScript
source: "<<<<<<< HEAD\n// Set options\nvar options = {\n sheetId: 4583173393803140,\n\
\ rowId: 2361756178769796\n};\n\n// Get row\nsmartsheet.sheets.getRow(options)\n\
\ .then(function(row) {\n console.log(row);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n=======\nvar fs = require('fs');\n\
var request = require('request');\n\nvar sheetId = 1639534409607044;\nvar\
\ rowId = 3344087179913092;\nvar columnId = 1735559124150148;\n\n// Step\
\ 1: Identify the cell that contains an image\n\nsmartsheet.sheets.getRow({\n\
\ sheetId: sheetId,\n rowId: rowId\n}).then(row => {\n var cell = row.cells.find(cell\
\ => cell.columnId === columnId);\n\n// Step 2: Get image info from cell\n\
\n var image = cell.image;\n var imageId = image.id;\n var localFileName\
\ = image.altText;\n\n// Step 3: Build list of image URLs\n\nsmartsheet.images.listImageUrls({\n\
\ body: [{imageId: imageId}]\n }).then(result => {\n var imageUrl\
\ = result.imageUrls[0].url;\n\n// Step 4: Download the image\n\n request(imageUrl).pipe(fs.createWriteStream(localFileName));\n\
\ });\n});\n>>>>>>> develop\n"
label: Node.js
- lang: Python
source: "<<<<<<< HEAD\n# Include discussions, attachments, columns, and columnType\n\
row = smartsheet_client.Sheets.get_row(\n 4583173393803140, # sheet_id\n\
\ 2361756178769796, # row_id\n include='discussions,attachments,columns,columnType'\n\
)\n=======\nsheetId = 1639534409607044\nrowId = 3344087179913092\ncolumnId\
\ = 1735559124150148\n\n# Steps 1 and 2: Locate the cell and obtain the\
\ imageId\nrow = smartsheet_client.Sheets.get_row(sheet_id, row_id)\ncell\
\ = row.get_column(column_id)\nimage = cell.image\nimage_id = image.id\n\
\n# Automate using Alt Text as the file name\nfilename = getattr(image,\
\ 'alt_text', default_filename)\n\n# Step 3: Obtain a temporary image URL\n\
imageUrl = smartsheet.models.ImageUrl( { \"imageId\": image_id } )\nresponse\
\ = smartsheet_client.Images.get_image_urls([imageUrl])\nurl = response.image_urls[0].url\n\
\n# Step 4: Download the image\nimport requests\nresponse = requests.get(url)\n\
if response.status_code == 200:\n with open(filename, 'wb') as f:\n \
\ f.write(response.content)\n>>>>>>> develop\n"
- lang: Ruby
source: "<<<<<<< HEAD\nrow = smartsheet.sheets.rows.get(\n sheet_id: 4583173393803140,\n\
\ row_id: 2361756178769796\n)\n=======\nrequire 'open-uri'\n\nsheet_id\
\ = 1639534409607044\nrow_id = 3344087179913092\ncolumn_id = 1735559124150148\n\
default_filename = 'my_image.png'\n\n# Steps 1 and 2: Locate the cell and\
\ obtain the imageId\nrow = smartsheet.sheets.rows.get(sheet_id: sheet_id,\
\ row_id: row_id)\ncell = row[:cells].select { |cell| cell[:column_id] ==\
\ column_id }.first\nimage = cell[:image]\nimage_id = image[:id]\n\n# Automate\
\ using Alt Text as the file name\nfilename = image[:alt_text] || default_filename\n\
\n# Step 3: Obtain a temporary image URL\nresponse = smartsheet.sheets.list_image_urls(body:\
\ [{image_id: image_id}])\nurl = response[:image_urls][0][:url]\n\n# Step\
\ 4: Download the image\nimage_download = open(url)\nIO.copy_stream(image_download,\
\ filename)\n>>>>>>> develop\n"
/sheets/{sheetId}/rows/{rowId}/attachments:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Row Attachments
description: >
Gets a list of all attachments that are on the row, including row and
discussion-level attachments.
operationId: attachments-listOnRow
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of attachments
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult attachments\
\ = smartsheet.SheetResources.RowResources.AttachmentResources.ListAttachments(\n\
\ 2252168947361668, // sheetId\n 4293147074291588, \
\ // rowId\n null // PaginationParameters\n\
);\n"
- lang: Java
source: "// Omit pagination\nPagedResult attachments = smartsheet.sheetResources().rowResources().attachmentResources().getAttachments(\n\
\ 2252168947361668L, // long sheetId\n 4293147074291588L,\
\ // long rowId\n null // PaginationParameters\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ rowId: 4293147074291588\n};\n\n// List row attachments\nsmartsheet.sheets.getRowAttachments(options)\n\
\ .then(function(attachmentsList) {\n console.log(attachmentsList);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Attachments.list_row_attachments(\n\
\ 2252168947361668, # sheet_id\n 4293147074291588, # row_id\n\
\ include_all=True)\nattachments = response.data\n\n# Sample 2: Paginate\
\ the list\nresponse = smartsheet_client.Attachments.list_row_attachments(\n\
\ 2252168947361668, # sheet_id\n 4293147074291588, # row_id\n\
\ page_size=10,\n page=1)\npages = response.total_pages\nattachments =\
\ response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.rows.attachments.list(\n sheet_id:\
\ 2252168947361668,\n row_id: 4293147074291588\n)\nattachments = response[:data]\n"
post:
summary: Attach File or URL to Row
description: |
Attaches a file to the row. The URL can be any of the following:
* Normal URL (attachmentType "LINK")
* Box.com URL (attachmentType "BOX_COM")
* Dropbox URL (attachmentType "DROPBOX")
* Egnyte URL (attachmentType "EGNYTE")
* Evernote URL (attachmentType "EVERNOTE")
* Google Drive URL (attachmentType "GOOGLE_DRIVE")
* OneDrive URL (attachmentType "ONEDRIVE")
For multipart uploads please use "multipart/form-data" content type.
operationId: row-attachments-attachFile
tags:
- attachments
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
multipart/form-data:
schema:
type: object
properties:
name:
type: string
filename:
type: string
format: binary
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1attachments/post/requestBody/content/application~1json/schema'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D~1attachments/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/attachments\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/msword\" \\\n-H 'Content-Disposition: attachment; filename=\"\
ProgressReport.docx\"' \\\n-H \"Content-Length: FILE_SIZE\" \\\n-X POST\
\ \\\n--data-binary @ProgressReport.docx\n"
- lang: C#
source: "Attachment attachment = smartsheet.SheetResources.RowResources.AttachmentResources.AttachFile(\n\
\ 9283173393803140, // sheetId\n 0123456789012345, \
\ // rowId\n filePath,\n \"application/msword\"\n);\n"
- lang: Java
source: "// Specify file to be attached\nFile file = new File(\"/Users/jdoe/Documents/ProgressReport.docx\"\
);\n\n// Attach file to row\n Attachment attachment = smartsheet.sheetResources().rowResources().attachmentResources().attachFile(\n\
\ 9283173393803140L, // long sheetId\n 0123456789012345L,\
\ // long rowId\n file,\n \"application/msword\"\n \
\ );\n"
- lang: JavaScript
source: "// Enable FileStream\nvar fs = require(\"fs\")\n\n// Set options\n\
var options = {\n sheetId: 1696803624483716,\n rowId: 1049041355358596,\n\
\ fileSize: 20765,\n fileName: \"ProgressReport.docx\",\n fileStream:\
\ fs.createReadStream(\"/Users/jdoe/Documents/ProgressReport.docx\")\n};\n\
\n// Attach file to row\nsmartsheet.sheets.addRowFileAttachment(options)\n\
\ .then(function(attachment) {\n console.log(attachment);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_attachment = smartsheet_client.Attachments.attach_file_to_row(\n\
\ 9283173393803140, # sheet_id\n 0123456789012345, # row_id\n\
\ ('ProgressReport.docx',\n open('/path/to/ProgressReport.docx', 'rb'),\n\
\ 'application/msword')\n)\n"
- lang: Ruby
source: "# Sample 1: Attach file from path\nresponse = smartsheet.sheets.rows.attachments.attach_file_from_path(\n\
\ sheet_id: 4583173393803140,\n row_id: 4293147074291588,\n path: '/Users/jdoe/Documents/ProgressReport.docx'\n\
)\nnew_attachment = response[:result]\n\n# Sample 2: Attach file\nfilename\
\ = '/Users/jdoe/Documents/ProgressReport.docx'\nfile = File.open(filename)\n\
file_length = File.size(filename)\n\nresponse = smartsheet.sheets.rows.attachments.attach_file(\n\
\ sheet_id: 4583173393803140,\n row_id: 4293147074291588,\n file: file,\n\
\ filename: filename,\n file_length: file_length\n)\nnew_attachment =\
\ response[:result]\n"
/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D/parameters/1'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1columns~1%7BcolumnId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Add Image to Cell
description: Uploads an image to the specified cell within a sheet.
operationId: addImageToCell
tags:
- cellImages
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/0'
- name: Content-Length
in: header
description: >
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
schema:
type: integer
example: 5463
- name: altText
in: query
description: Url-encoded alternate text for the image
schema:
type: string
required: false
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/parameters/2'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/components/schemas/ReportRow/allOf/0'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages?altText=my%20image'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ image/jpeg\" \\\n-H 'Content-Disposition: attachment; filename=\"picture.jpg\"\
' \\\n-H \"Content-Length: FILE_SIZE\" \\\n-X POST \\\n--data-binary @picture.jpg\n"
- lang: C#
source: "// Set options\nImage image = new Image\n {\n AltText = \"Caution\
\ Sign\",\n Height = 16,\n Width = 16\n };\n\nsmartsheet.SheetResources.RowResources.CellResources.AddImageToCell(\n\
\ 1696831624483716, // sheetId\n 1049441315358596, // rowId\n 74761903175665540,\
\ // columnId\n \"/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png\"\
,\n \"image\"\n);\n"
- lang: Java
source: "// Set options\nImage image = new Image()\n .setAltText(\"\
Caution sign\")\n .setHeight(16L)\n .setWidth(16L);\n\n \
\ smartsheet.sheetResources().rowResources().cellResources().addImageToCell(\n\
\ 1639534409607044L, // sheetId\n 1049441315358596L,\
\ // rowId\n 74761903175665540L, // columnId\n \"\
/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png\",\n \"\
image\"\n );\n"
- lang: JavaScript
source: "// Enable FileStream\nvar fs = require(\"fs\")\n\n// Set options\n\
var options = {\n sheetId: 1696831624483716,\n rowId: 1049441315358596,\n\
\ columnId: 74761903175665540,\n fileSize: 458, // Must be exact bytes;\
\ no rounding\n fileName: \"img_pl_decisionshapesHold.png\",\n fileStream:\
\ fs.createReadStream(\"/Users/jroe/Documents/images/img_pl_decisionshapesHold.png\"\
),\n queryParameters: {\n \"altText\": \"Caution sign\",\n \"overrideValidation\"\
: true\n }\n };\n\n // Add image to cell\n smartsheet.sheets.addImageToCell(options)\n\
\ .then(function(image) {\n console.log(image);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "sheet_id = 1696831624483716\ncolumn_id = 74761903175665540\nrow_id\
\ = 1049441315358596\ncaution_pic = \"/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png\"\
\nfile_type = \"png\"\nsmartsheet_client.Cells.add_image_to_cell(sheet_id,\
\ row_id, column_id, caution_pic, file_type)\n"
- lang: Ruby
source: "# Sample 1: Add image from path\nresponse = smartsheet.sheets.cells.add_image_from_path(\n\
\ sheet_id: 1696831624483716,\n row_id: 1049441315358596,\n column_id:\
\ 74761903175665540,\n path: '/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png'\n\
)\nnew_image = response[:result]\n\n# Sample 2: Add image\nfilename = '/Users/jdoe/Documents/images/img_pl_decisionshapesHold.png'\n\
file = File.open(filename)\nfile_length = File.size(filename)\n\nresponse\
\ = smartsheet.sheets.cells.add_image(\n sheet_id: 1696831624483716,\n\
\ row_id: 1049441315358596,\n column_id: 74761903175665540,\n file: file,\n\
\ filename: filename,\n file_length: file_length\n)\nnew_image = response[:result]\n"
/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D/parameters/1'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1columns~1%7BcolumnId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Cell History
description: |
Gets the cell modification history.
operationId: cellHistory-get
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of elements to copy:
* **columnType** - includes the columnType attribute for each Cell object
* **objectValue** - when used in combination with a level query parameter,
includes the email addresses for a multi-contact cell.
schema:
type: string
enum:
- columnType
- objectValue
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D/get/parameters/6'
tags:
- cells
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: List of cell history objects
type: array
items:
type: object
allOf:
- $ref: '#/components/schemas/CellDataItem/properties/cell'
properties:
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedBy:
description: User object containing the name and email
of the user that made the change.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history?include=columnType'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Sample 1: Omit 'include' parameter and pagination parameters\n\
PaginatedResult results = smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(\n\
\ 9283173393803140, // sheetId\n 0123456789012345, \
\ // rowId\n 4567890123456789, // columnId\n null,\
\ // IEnumerable includes\n null\
\ // PaginationParameters\n);\n\n// Sample 2:\
\ Specify 'include' parameter with value of \"COLUMN_TYPE\" and 'includeAll'\
\ parameter with value of 'true'\nPaginatedResult results =\
\ smartsheet.SheetResources.RowResources.CellResources.GetCellHistory(\n\
\ 9283173393803140, // sheetId\n 0123456789012345, \
\ // rowId\n 4567890123456789, // columnId\n new\
\ CellInclusion[] { CellInclusion.COLUMN_TYPE },\n new PaginationParameters(\n\
\ true, // Boolean includeAll\n null, \
\ // int pageSize\n null) // int\
\ page\n);\n"
- lang: Java
source: "// Omit pagination\nPagedResult cellHistory = smartsheet.sheetResources().rowResources().cellResources().getCellHistory(\n\
\ 9283173393803140L, // long sheetId\n 0123456789012345L,\
\ // long rowId\n 4567890123456789L, // long columnId\n\
\ null // PaginationParameters\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 9283173393803140,\n \
\ rowId: 0123456789012345,\n columnId: 4567890123456789\n};\n\n// Get cell\
\ history\nsmartsheet.sheets.getCellHistory(options)\n .then(function(history)\
\ {\n console.log(history);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: Get history\nresponse = smartsheet_client.Cells.get_cell_history(\n\
\ 9283173393803140, # sheet_id\n 0123456789012345, # row_id\n\
\ 4567890123456789, # column_id\n include_all=True)\nrevisions =\
\ response.data\n\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Cells.get_cell_history(\n\
\ 9283173393803140, # sheet_id\n 0123456789012345, # row_id\n\
\ 4567890123456789, # column_id\n page_size=5,\n page=1)\npages\
\ = response.total_pages\nrevisions = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.cells.get_history(\n sheet_id: 9283173393803140,\n\
\ row_id: 0123456789012345,\n column_id: 4567890123456789\n)\nrevisions\
\ = response[:data]\n"
/sheets/{sheetId}/rows/{rowId}/discussions:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Discussions with a Row
description: >
Gets a list of all discussions associated with the specified row.
Remember that discussions are containers
for the conversation thread. To see the entire thread, use the include=comments
parameter.
operationId: row-discussions-list
tags:
- discussions
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of discussions
type: array
items:
$ref: '#/components/schemas/Proof/properties/discussions/items'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions?include=comments,attachments'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "// Sample 1: Omit 'include' parameter and pagination parameters\n\
PaginatedResult results = smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(\n\
\ 2252168947361668, // sheetId\n 4293147074291588, \
\ // rowId\n null, // IEnumerable\
\ include\n null // PaginationParameters\n\
);\n\n// Sample 2: Specify 'include' parameter with values of 'COMMENTS'\
\ and 'ATTACHMENTS', and 'includeAll' parameter with value of 'true'\nPaginatedResult\
\ results = smartsheet.SheetResources.RowResources.DiscussionResources.ListDiscussions(\n\
\ 2252168947361668, // sheetId\n 4293147074291588, \
\ // rowId\n new DiscussionInclusion[] { DiscussionInclusion.COMMENTS,\
\ DiscussionInclusion.ATTACHMENTS },\n new PaginationParameters(\n true,\
\ // includeAll\n null, \
\ // int pageSize\n null) // int page\n\
);\n"
- lang: Java
source: "// Sample 1: Omit 'include' parameter and pagination parameters\n\
PagedResult results = smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(\n\
\ 2252168947361668L, // long sheetId\n 4293147074291588L,\
\ // long rowId\n null, // PaginationParameters\n\
\ null // EnumSet includes\n\
\ );\n\n// Sample 2: Specify pagination parameter 'includeAll'\n\
PaginationParameters parameters = new PaginationParameters()\n .setIncludeAll(true);\n\
\n// Get all row discussions (specify 'include' parameter with values of\
\ 'COMMENTS' and 'ATTACHMENTS', and 'includeAll' parameter with value of\
\ 'true')\nPagedResult results = smartsheet.sheetResources().rowResources().discussionResources().listDiscussions(\n\
\ 2252168947361668L, // long sheetId\n 4293147074291588L,\
\ // long rowId\n parameters,\n EnumSet.of(DiscussionInclusion.COMMENTS,\
\ DiscussionInclusion.ATTACHMENTS)\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 2252168947361668,\n \
\ rowId: 4293147074291588\n};\n\n// List row discussions\nsmartsheet.sheets.getRowDiscussions(options)\n\
\ .then(function(discussionList) {\n console.log(discussionList);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Discussions.get_row_discussions(\n\
\ 2252168947361668, # sheet_id\n 4293147074291588, \
\ # row_id\n include_all=True)\ndiscussions = response.data\n\n\
# Sample 2: Paginate the list\nresponse = smartsheet_client.Discussions.get_row_discussions(\n\
\ 2252168947361668, # sheet_id\n 4293147074291588, \
\ # row_id\n page_size=10)\npages = response.total_pages \
\ # starts on page 1 by default\ndiscussions = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.discussions.list_row_discussions(\n\
\ sheet_id: 4583173393803140,\n row_id: 4293147074291588\n)\ndiscussions\
\ = response[:data]\n"
post:
summary: Create a Discussion on a Row
description: >
Creates a new discussion on a row. To create a discussion with an
attachment please use "multipart/form-data" content type.
operationId: row-discussions-create
tags:
- discussions
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions/post/requestBody/content/application~1json/schema'
multipart/form-data:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1discussions/post/requestBody/content/multipart~1form-data/schema'
encoding:
discussion:
contentType: application/json
file:
contentType: application/octet-stream
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D~1discussions/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "# Example request: create discussion on row (without attachment)\n\
\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"comment\": {\"text\":\"This\
\ text is the body of the first comment\"}}'\n\n# Example request: create\
\ discussion on row (with attachment)\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/discussions\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ multipart/form-data\" \\\n-X POST \\\n-F 'discussion={ \"comment\": {\
\ \"text\": \"This text is the body of the first comment\" } };type=application/json'\
\ \\\n-F \"file=@insurance_benefits.pdf;type=application/octet-stream\""
- lang: C#
source: "// Example request: create discussion on row (without attachment)\n\
\n// Create discussion (including the comment)\nDiscussion discussionSpecification\
\ = new Discussion\n{\n Comment = new Comment\n {\n Text = \"This\
\ text is the body of the first comment\"\n },\n Comments = null \
\ // workaround for SDK issue\n};\n\n// Add discussion to row\nDiscussion\
\ newDiscussion = smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussion(\n\
\ 9283173393803140, // sheetId\n 0123456789012345, \
\ // rowId\n discussionSpecification\n);\n\n// Example request:\
\ create discussion on row (with attachment)\n\n// Create discussion (including\
\ the comment)\nDiscussion discussionSpecification = new Discussion\n{\n\
\ Comment = new Comment\n {\n Text = \"This text is the body of the\
\ first comment\"\n },\n Comments = null // workaround for SDK\
\ issue\n};\n\n// Add discussion to row\nDiscussion newDiscussion = smartsheet.SheetResources.RowResources.DiscussionResources.CreateDiscussionWithAttachment(\n\
\ 9283173393803140, // sheetId\n 0123456789012345, \
\ // rowId\n discussionSpecification,\n filePath,\n \
\ \"application/octet-stream\"\n);\n"
- lang: Java
source: "// Example request: create discussion on row (without attachment)\n\
\n// Create comment\nComment commentSpecification = new Comment()\n \
\ .setText(\"This text is the body of the first comment\");\n\n// Create\
\ discussion (including the comment)\n Discussion discussionSpecification\
\ = new Discussion()\n .setComment(commentSpecification)\n \
\ .setComments(null); // workaround for SDK issue\n\n// Add discussion\
\ to row\n Discussion newDiscussion = smartsheet.sheetResources().rowResources().discussionResources().createDiscussion(\n\
\ 9283173393803140L, // sheetId\n 0123456789012345L,\
\ // rowId\n discussionSpecification\n );\n\n// Example\
\ request: create discussion on row (with attachment)\n\n// Create comment\n\
\ Comment commentSpecification = new Comment()\n .setText(\"\
This text is the body of the first comment\");\n\n// Create discussion (including\
\ the comment)\n Discussion discussionSpecification = new Discussion()\n\
\ .setComment(commentSpecification)\n .setComments(null);\
\ // workaround for SDK issue\n\n// Set file path\n File file\
\ = new File(filePath);\n\n// Add discussion to row\n Discussion\
\ newDiscussion = smartsheet.sheetResources().rowResources().discussionResources().createDiscussionWithAttachment(\n\
\ 9283173393803140L, // long sheetId\n 0123456789012345L,\
\ // long rowId\n discussionSpecification,\n file,\n\
\ \"application/octet-stream\"\n );\n"
- lang: JavaScript
source: "// Example request: create discussion on row (without attachment)\n\
\n// Specify discussion\nvar discussion = {\n \"comment\": {\n \"text\"\
: \"This text is the body of the first comment\"\n }\n};\n\n// Set options\n\
var options = {\n sheetId: 2252168947361668,\n rowId: 4293147074291588,\n\
\ body: discussion\n };\n\n// Add discussion to row\nsmartsheet.sheets.createRowDiscussion(options)\n\
\ .then(function(newDiscussion) {\n console.log(newDiscussion);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n\n// Example\
\ request: create discussion on row (with attachment)\n\n// Multipart operations\
\ are not supported by the Node SDK. Instead, see instructions to Create\
\ Discussion on Row, and then Attach File to Comment.\n"
label: Node.js
- lang: Python
source: "# Example request: create discussion on row (without attachment)\n\
\nresponse = smartsheet_client.Discussions.create_discussion_on_row(\n \
\ 9283173393803140, # sheet_id\n 0123456789012345, \
\ # row_id\n smartsheet.models.Discussion({\n 'comment': smartsheet.models.Comment({\n\
\ 'text': 'This text is the body of the first comment'\n })\n })\n\
)\n\n# Example request: create discussion on row (with attachment)\n\n#\
\ Add discussion to row\nresponse = smartsheet_client.Discussions.create_discussion_on_row_with_attachment(\n\
\ 9283173393803140, # sheet_id\n 0123456789012345, # row_id\n\
\ smartsheet.models.Discussion({\n 'comment': smartsheet.models.Comment({\n\
\ 'text': 'This text is the body of the first comment'\n })\n }),\n\
\ ('photo.jpg', open('/path/to/photo.jpg', 'rb'), 'image/jpeg')\n)\n"
- lang: Ruby
source: "# Example request: create discussion on row (without attachment)\n\
\n# Set options\nbody = {\n comment: {\n text: 'This text is the body\
\ of the first comment'\n }\n}\n\n# Create discussion on row\nresponse\
\ = smartsheet.sheets.discussions.create_on_row(\n sheet_id: 4583173393803140,\n\
\ row_id: 4293147074291588,\n body: body\n)\nnew_discussion = response[:result]\n\
\n# Example request: create discussion on row (with attachment)\n\n# Multipart\
\ operations are not supported by the Ruby SDK. Instead, see instructions\
\ to Create Discussion on Row, and then Attach File to Comment.\n"
/sheets/{sheetId}/rows/{rowId}/proofs:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Create Proof
description: |
Creates a proof on a row.
operationId: proofs-create
tags:
- proofs
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/components/schemas/Row/properties/proofs'
properties:
version:
description: New version of the sheet. Applicable only for operations
which update sheet data.
type: number
nullable: true
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/rows/{rowId}/proofs\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Disposition:\
\ attachment; filename=\"giphy.gif\"\" \\\n-H \"Content-Type: image/gif\"\
\ \\\n--data-binary @giphy.gif\n-X POST \\"
/sheets/{sheetId}/sentupdaterequests:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Sent Update Requests
description: |
Gets a summarized list of all sent update requests on the sheet.
Only the following fields are returned in the response:
* **id**
* **message**
* **sendTo**
* **sentAt**
* **sentBy**
* **status**
* **subject**
* **updateRequestId**
operationId: sentupdaterequests-list
tags:
- updateRequests
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: The list of SentUpdateRequest objects
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of Sent Update Requests
type: array
items:
type: object
properties:
id:
description: The Id of the sent update request.
type: number
columnIds:
description: The Ids of columns included in the request.
type: array
items:
type: number
rowIds:
description: The Ids of rows where an update is requested.
type: array
items:
type: number
updateRequestId:
description: The Id of the originating update request.
type: number
includeAttachments:
description: Indicates whether the attachments were included
in the email.
type: boolean
includeDiscussions:
description: Indicates whether the discussions were included
in the email.
type: boolean
message:
description: The message of the email. Max 10000 characters.
type: string
sentAt:
description: The date and time for when the sent update
request was sent to the recipient.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
sentBy:
description: >
`User` object containing `name` and `email` of
the sender.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
sentTo:
description: Recipient object.
allOf:
- $ref: '#/components/schemas/AutomationAction/oneOf/1/properties/recipients/items'
status:
description: The status of the sent update request.
type: string
enum:
- CANCELED
- COMPLETE
- PENDING
subject:
description: The subject of the email.
type: string
examples:
EmailResponse:
summary: Sent to Individual User
value:
pageNumber: 1
pageSize: 50
totalPages: 25
totalCount: 136
data:
- id: 3319834533488516
updateRequestId: 6742614230755204
message: Some message
sentAt: 2020-05-29T03:14:28Z
sentBy:
email: jane.doe@smartsheet.com
name: Jane Doe
sentTo:
email: person@company.org
status: COMPLETE
subject: Sample Bi-Weekly Update Request
GroupResponse:
summary: Sent to Group
value:
pageNumber: 1
pageSize: 50
totalPages: 25
totalCount: 136
data:
- id: 3319834533488516
updateRequestId: 6742614230755204
message: Some message
sentAt: 2020-05-29T03:14:28Z
sentBy:
email: jane.doe@smartsheet.com
name: Jane Doe
sentTo:
groupId: '197256463378308'
status: COMPLETE
subject: Sample Bi-Weekly Update Request
x-codeSamples:
- lang: cURL
source: "# Example request: list sent update requests\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/sentupdaterequests\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "# Example request: list sent update requests\n\nPaginatedResult\
\ results = smartsheet.SheetResources.UpdateRequestResources.ListSentUpdateRequests(\n\
\ 1639534409607044, // sheetId\n null //\
\ PaginationParameters\n);"
- lang: Java
source: "# Example request: list sent update requests\n\nPagedResult\
\ results = smartsheet.sheetResources().updateRequestResources().listSentUpdateRequests(\n\
\ 1639534409607044L, // long sheetId\n null \
\ // PaginationParameters\n);"
- lang: JavaScript
source: "# Example request: list sent update requests\n\n// Set options\n\
var options = {\n sheetId: 1639534409607044\n};\n\n// List sent update\
\ requests\nsmartsheet.sheets.getAllSentUpdateRequests(options)\n .then(function(requestsList)\
\ {\n console.log(requestsList);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "# Example request: list sent update requests\n\nresponse = smartsheet_client.Sheets.list_sent_update_requests(\n\
\ 5190835902932868) # sheet_id\nupdate_requests = response.data"
- lang: Ruby
source: "# Example request: list sent update requests\n\nresponse = smartsheet.update_requests.sent.list(\n\
\ sheet_id: 3294745817573252\n)\nupdate_requests = response[:data]"
/sheets/{sheetId}/sentupdaterequests/{sentUpdateRequestId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: sentUpdateRequestId
in: path
required: true
description: ID of the sent update request
schema:
type: string
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Sent Update Request
description: |
Gets the specified sent update request on the sheet.
operationId: sentupdaterequest-get
tags:
- updateRequests
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: SentUpdateRequest object
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1sentupdaterequests/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
x-codeSamples:
- lang: cURL
source: "# Example request: get sent update request\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/sentupdaterequests/{sentUpdateRequestId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "# Example request: get sent update request\n\nSentUpdateRequest results\
\ = smartsheet.SheetResources.UpdateRequestResources.GetSentUpdateRequest(\n\
\ 3285357287499652, // sheetId\n 2303451729291140 // sentUpdateRequestId\n\
);"
- lang: Java
source: "# Example request: get sent update request\n\nSentUpdateRequest results\
\ = smartsheet.sheetResources().updateRequestResources().getSentUpdateRequest(\n\
\ 1639534409607044L, // long sheetId\n 67287475611524L \
\ // long sentUpdateRequestId\n);"
- lang: JavaScript
source: "# Example request: get sent update request\n\n// Set options\nvar\
\ options = {\n sheetId: 1639534409607044,\n sentUpdateRequestId:\
\ 67287475611524\n};\n\n// Get sent update request\nsmartsheet.sheets.getSentUpdateRequest(options)\n\
\ .then(function(updateRequest) {\n console.log(updateRequest);\n\
\ })\n .catch(function(error) {\n console.log(error);\n \
\ });"
label: Node.js
- lang: Python
source: "# Example request: get sent update request\n\nresponse = smartsheet_client.Sheets.get_sent_update_request(\n\
\ 5190835902932868, # sheet_id\n 7510551698925444 # update_request_id\n\
)"
- lang: Ruby
source: "# Example request: get sent update request\n\nresponse = smartsheet.update_requests.sent.get(\n\
\ sheet_id: 3294745817573252,\n sent_update_request_id: 965780272637828\n\
)"
delete:
summary: Delete Sent Update Request
description: >
Deletes the specified sent update request.
**Delete operation is supported only when the specified sent update request
is in the pending status.
Deleting a sent update request that was already completed by recipient is
not allowed.**
operationId: sentupdaterequest-delete
tags:
- updateRequests
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
- WRITE_SHEETS
responses:
'200':
description: Result object
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
x-codeSamples:
- lang: cURL
source: "# Example request: delete sent update request\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/sentupdaterequests/{sentUpdateRequestId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE"
- lang: C#
source: "# Example request: delete sent update request\n\nsmartsheet.SheetResources.UpdateRequestResources.DeleteSentUpdateRequest(\n\
\ 3285357287499652, // sheetId\n 2303451729291140 // sentUpdateRequestId\n\
);"
- lang: Java
source: "# Example request: delete sent update request\n\nsmartsheet.sheetResources().updateRequestResources().deleteSentUpdateRequest(\n\
\ 1639534409607044L, // long sheetId\n 965780272637828L \
\ // long sentUpdateRequestId\n);"
- lang: JavaScript
source: "# Example request: delete sent update request\n\n// Set options\n\
var options = {\n sheetId: 1639534409607044,\n sentUpdateRequestId:\
\ 965780272637828\n};\n\n// Delete sent update request\nsmartsheet.sheets.deleteSentUpdateRequest(options)\n\
\ .then(function(result) {\n console.log(result);\n })\n \
\ .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "# Example request: delete sent update request\n\nsmartsheet_client.Sheets.delete_sent_update_request(\n\
\ 5190835902932868, # sheet_id\n 381297098024836 # sent_update_request_id\n\
)"
- lang: Ruby
source: "# Example request: delete sent update request\n\nsmartsheet.update_requests.sent.delete(\n\
\ sheet_id: 3294745817573252,\n sent_update_request_id: 965780272637828\n\
)"
/sheets/{sheetId}/summary:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Sheet Summary
description: Returns object containing array of summary fields. Allows for pagination
of results.
operationId: list-summary-fields
tags:
- sheetSummary
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of elements to include in the response.
* **format**: includes format info for cells, rows, and summary fields
* **writerInfo**: includes createdBy and modifiedBy attributes for rows
and summary fields
schema:
type: string
enum:
- format
- writerInfo
- name: exclude
in: query
required: false
description: >
A comma-separated list of elements to not include in the response.
* **displayValue**: excludes displayValue info for cells, rows, and summary
fields
* **image**: excludes image attributes for cells and summary fields
* **imageAltText**: excludes alt text for cells and summary fields
schema:
type: string
enum:
- displayValue
- image
- imageAltText
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Sheet/properties/summary'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary?include=writerInfo\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "smartsheet.SheetResources.SummaryResources.GetSheetSummary(\n 1421228469708676,\
\ // sheetId\n new List { SummaryFieldInclusion.FORMAT,\
\ SummaryFieldInclusion.WRITER_INFO },\n new List\
\ { SummaryFieldExclusion.DISPLAY_VALUE }\n);\n"
- lang: Java
source: "smartsheet.sheetResources().summaryResources().getSheetSummary(\n\
\ 1421228469708676L, // long sheetId\n EnumSet.of(SummaryFieldInclusion.FORMAT,\
\ SummaryFieldInclusion.WRITERINFO),\n EnumSet.of(SummaryFieldExclusion.DISPLAYVALUE)\n\
\ );\n"
- lang: JavaScript
source: "var options = {\n sheetId: 1421228469708676\n};\n\nsmartsheet.sheets.getSummary(options)\n\
\ .then(function(summary) {\n console.log(summary);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.get_sheet_summary(\n 1421228469708676,\
\ # sheet_id\n include='format,writerInfo',\n exclude='displayValue'\n\
)\n"
- lang: Ruby
source: "smartsheet.sheets.summaries.get(sheet_id: 1421228469708676)\n"
/sheets/{sheetId}/summary/fields:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Summary Fields
description: Returns object containing array of summary fields. Allows for pagination
of results.
operationId: list-summary-fields-paginated
tags:
- sheetSummary
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary/get/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary/get/parameters/1'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: List of Summary Fields
type: array
items:
$ref: '#/components/schemas/CellDataItem/properties/profileField'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "PaginationParameters paginationParameters = new PaginationParameters(\n\
\ false, // includeAll\n 100, // pageSize\n 1 // page\n);\n\
smartsheet.SheetResources.SummaryResources.GetSheetSummaryFields(\n 1421228469708676,\
\ // sheetId\n new List { SummaryFieldInclusion.FORMAT,\
\ SummaryFieldInclusion.WRITER_INFO },\n new List\
\ { SummaryFieldExclusion.DISPLAY_VALUE },\n paginationParameters\n);\n"
- lang: Java
source: "PaginationParameters paginationParameters = new PaginationParameters(\n\
\ false, // includeAll\n 100, // pageSize\n 1\
\ // page\n );\nsmartsheet.sheetResources().summaryResources().getSheetSummaryFields(\n\
\ 1421228469708676L, // long sheetId\n EnumSet.of(SummaryFieldInclusion.FORMAT,\
\ SummaryFieldInclusion.WRITERINFO),\n EnumSet.of(SummaryFieldExclusion.DISPLAYVALUE),\n\
\ paginationParameters\n );\n"
- lang: JavaScript
source: "var options = {\n sheetId: 1421228469708676\n};\n\nsmartsheet.sheets.getSummaryFields(options)\n\
\ .then(function(summary) {\n console.log(summary);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.get_sheet_summary_fields(\n 1421228469708676,\
\ # sheet_id\n include='format,writerInfo',\n exclude='displayValue',\n\
\ 100, # page_size\n 1, # page\n False # include_all\n\
)\n"
- lang: Ruby
source: "smartsheet.sheets.summaries.get_fields(sheet_id: 1421228469708676)\n"
put:
summary: Update Summary Fields
description: Updates the summary fields for the given sheet.
operationId: update-summary-fields
tags:
- sheetSummary
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
parameters:
- name: renameIfConflict
description: Set to true if you want to override the requirement for unique
summary field names. Repeated names will be adjusted by appending "(1)"
or similar after the field name.
in: query
required: false
schema:
type: boolean
default: false
requestBody:
description: Array of SummaryField objects
required: true
content:
application/json:
schema:
type: array
items:
type: object
description: SummaryField object to update.
properties:
id:
description: SummaryField Id.
type: number
contactOptions:
description: Array of ContactOption objects to specify a pre-defined
list of values for the column. Column type must be CONTACT_LIST.
type: array
items:
$ref: '#/components/schemas/Column/properties/contactOptions/items'
format:
description: The format descriptor. Only returned if the include
query string parameter contains format and this column has a
non-default format applied to it.
type: string
formula:
description: The formula for a cell, if set.
type: string
hyperlink:
$ref: '#/components/schemas/Cell/properties/hyperlink'
image:
$ref: '#/components/schemas/Cell/properties/image'
index:
description: Field index or position. This number is zero-based.
type: number
locked:
description: Indicates whether the field is locked.
type: boolean
objectValue:
$ref: '#/components/schemas/Cell/properties/objectValue'
options:
description: When applicable for PICKLIST column type. Array of
the options available for the field.
type: array
items:
type: string
symbol:
description: When applicable for PICKLIST column type.
type: string
title:
description: Arbitrary name, must be unique within summary.
type: string
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
validation:
description: Indicates whether summary field values are restricted
to the type.
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
description: A list of updated summary fields
properties:
result:
type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary~1fields/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary~1fields/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '[{ \\\n\t\"id\": 5629723890335892,\
\ \\\n\t\"type\": \"CONTACT_LIST\", \\\n\t\"objectValue\": { \\\n\t\t\"\
objectType\": \"CONTACT\", \\\n\t\t\"email\": \"jane.roe@smartsheet.com\"\
, \\\n\t\t\"name\": \"Jane Roe\" \\\n\t}, \\\n\t\"index\": 2, \\\n\t\"title\"\
: \"Author\" \\\n}]'\n"
- lang: C#
source: "SummaryField summaryField = new SummaryField();\nsummaryField.Type\
\ = ColumnType.TEXT_NUMBER;\nsummaryField.ObjectValue = new StringObjectValue(\"\
Sally Smart\");\nsummaryField.Index = 2;\nsummaryField.Title = \"Author\"\
;\n\nsmartsheet.SheetResources.SummaryResources.UpdateSheetSummaryFields(\n\
\ 1421228469708676, // sheetId\n new SummaryField[] { summaryField\
\ },\n false // renameIfConflict\n);\n"
- lang: Java
source: "SummaryField summaryField = new SummaryField();\nsummaryField.setType(ColumnType.TEXT_NUMBER);\n\
summaryField.setObjectValue(new StringObjectValue(\"Sally Smart\"));\nsummaryField.setIndex(2);\n\
summaryField.setTitle(\"Author\");\n\nsmartsheet.sheetResources().summaryResources().updateSheetSummaryFields(\n\
\ 1421228469708676L, // long sheetId\n Arrays.asList(summaryField),\n\
\ false // renameIfConflict\n );\n"
- lang: JavaScript
source: "var options = {\n sheetId: 1421228469708676,\n body: [{\n id:\
\ 5629723890335892,\n objectValue: 'Accepted'\n }]\n};\n\nsmartsheet.sheets.updateSummaryFields(options)\n\
\ .then(function(summary) {\n console.log(summary);\n }).catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "summary_field1 = smartsheet.models.SummaryField()\nsummary_field1.type\
\ = ColumnType.TEXT_NUMBER\nsummary_field1.object_value = smartsheet.models.StringObjectValue('Sally\
\ Smart')\nsummary_field1.index = 2\nsummary_field1.title = 'Author'\n\n\
smartsheet_client.Sheets.update_sheet_summary_fields(\n 1421228469708676,\
\ # sheet_id\n [summary_field1],\n False # rename_if_conflict\n\
)\n"
- lang: Ruby
source: "smartsheet.sheets.summaries.update_fields(\n sheet_id: 1421228469708676,\n\
\ body: [{\n id: 5629723890335892,\n objectValue: 'Accepted'\n }]\n\
)\n"
delete:
summary: Delete Summary Fields
description: Deletes summary fields from the specified sheet.
operationId: delete-summary-fields
tags:
- sheetSummary
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
parameters:
- name: ids
in: query
required: true
description: |
A comma-separated list of Sheet Summary Field Ids.
schema:
type: string
- name: ignoreSummaryFieldsNotFound
description: If **true**, the operation will succeed even if some fieldIds
are not found.
in: query
required: false
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary~1fields/put/responses/200/content/application~1json/schema/allOf/0'
- type: object
description: A list of fieldIds corresponding to all summary fields
that were successfully deleted.
properties:
result:
type: array
items:
type: number
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary~1fields/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields?ids={fieldId1},{fieldId2},{fieldId3}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.SheetResources.SummaryResources.DeleteSheetSummaryFields(\n\
\ 1421228469708676, // sheetId\n new long[] { 1421228469708676, 1421228469708676,\
\ 1421228469708676 }, // summaryFieldIds\n true // ignoreSummaryFieldsNotFound\n\
);\n"
- lang: Java
source: "smartsheet.sheetResources().summaryResources().deleteSheetSummaryFields(\n\
\ 1421228469708676L, // long sheetId\n new HashSet(Arrays.asList(1421228469708676L,\
\ 1421228469708676L, 1421228469708676L)), // long summaryFieldIds\n \
\ true // ignoreSummaryFieldsNotFound\n );\n"
- lang: JavaScript
source: "var options = {\n sheetId: 1421228469708676,\n queryParameters:\
\ {\n ids: '207098194749316',\n '100091196549967',\n '450360473006272'\n\
\ }\n};\n\nsmartsheet.sheets.deleteSummaryFields(options)\n .then(function(summary)\
\ {\n console.log(summary);\n }).catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.delete_sheet_summary_fields(\n 1421228469708676,\
\ # sheet_id\n [1421228469708676, 1421228469708676, 1421228469708676],\
\ # summary_field_ids\n True # ignore_summary_fields_not_found\n\
)\n"
- lang: Ruby
source: "smartsheet.sheets.summaries.delete_fields(\n sheet_id: 1421228469708676,\n\
\ params: { ids: '207098194749316', '100091196549967', '450360473006272'\
\ }\n)\n"
post:
summary: Add Summary Fields
description: Creates one or more summary fields for the specified sheet.
operationId: add-summary-fields
tags:
- sheetSummary
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
parameters:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary~1fields/put/parameters/0'
requestBody:
description: Array of SummaryField objects
required: true
content:
application/json:
schema:
type: array
items:
type: object
description: SummaryField object to create.
properties:
contactOptions:
description: Array of ContactOption objects to specify a pre-defined
list of values for the column. Column type must be CONTACT_LIST.
type: array
items:
$ref: '#/components/schemas/Column/properties/contactOptions/items'
format:
description: The format descriptor. Only returned if the include
query string parameter contains format and this column has a
non-default format applied to it.
type: string
formula:
description: The formula for a cell, if set.
type: string
hyperlink:
$ref: '#/components/schemas/Cell/properties/hyperlink'
image:
$ref: '#/components/schemas/Cell/properties/image'
index:
description: Field index or position. This number is zero-based.
type: number
locked:
description: Indicates whether the field is locked.
type: boolean
objectValue:
$ref: '#/components/schemas/Cell/properties/objectValue'
options:
description: When applicable for PICKLIST column type. Array of
the options available for the field.
type: array
items:
type: string
symbol:
description: When applicable for PICKLIST column type.
type: string
title:
description: Arbitrary name, must be unique within summary.
type: string
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
validation:
description: Indicates whether summary field values are restricted
to the type.
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary~1fields/put/responses/200/content/application~1json/schema/allOf/0'
- type: object
description: A list of created summary fields
properties:
result:
type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary~1fields/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1summary~1fields/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{ \\\n\t\"type\": \"TEXT_NUMBER\"\
, \\\n\t\"objectValue\": \"Sally Smart\", \\\n\t\"index\": 2, \\\n\t\"title\"\
: \"Author\" \\\n}]'\n"
- lang: C#
source: "SummaryField summaryField = new SummaryField();\nsummaryField.Type\
\ = ColumnType.TEXT_NUMBER;\nsummaryField.ObjectValue = new StringObjectValue(\"\
Sally Smart\");\nsummaryField.Index = 2;\nsummaryField.Title = \"Author\"\
;\n\nsmartsheet.SheetResources.SummaryResources.AddSheetSummaryFields(\n\
\ 1421228469708676, // sheetId\n new SummaryField[] { summaryField\
\ },\n false // renameIfConflict\n);\n"
- lang: Java
source: "SummaryField summaryField = new SummaryField();\nsummaryField.setType(ColumnType.TEXT_NUMBER);\n\
summaryField.setObjectValue(new StringObjectValue(\"Sally Smart\"));\nsummaryField.setIndex(2);\n\
summaryField.setTitle(\"Author\");\n\nsmartsheet.sheetResources().summaryResources().addSheetSummaryFields(\n\
\ 1421228469708676L, // long sheetId\n Arrays.asList(summaryField),\n\
\ false // renameIfConflict\n );\n"
- lang: JavaScript
source: "var options = {\n sheetId: 1421228469708676,\n body: [{\n type:\
\ 'TEXT_NUMBER',\n objectValue: 'Sally Smart',\n index: 2,\n title:\
\ 'Author'\n }]\n};\n\nsmartsheet.sheets.addSummaryFields(options)\n .then(function(summary)\
\ {\n console.log(summary);\n }).catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "summary_field1 = smartsheet.models.SummaryField()\nsummary_field1.type\
\ = ColumnType.TEXT_NUMBER\nsummary_field1.object_value = smartsheet.models.StringObjectValue('Sally\
\ Smart')\nsummary_field1.index = 2\nsummary_field1.title = 'Author'\n\n\
smartsheet_client.Sheets.add_sheet_summary_fields(\n 1421228469708676,\
\ # sheet_id\n [summary_field1],\n False # rename_if_conflict\n\
)\n"
- lang: Ruby
source: "smartsheet.sheets.summaries.add_fields(\n sheet_id: 1421228469708676,\n\
\ body: [{\n type: 'TEXT_NUMBER',\n objectValue: 'Sally Smart',\n\
\ index: 2,\n title: 'Author'\n }]\n)\n"
/sheets/{sheetId}/summary/fields/{fieldId}/images:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: fieldId
in: path
schema:
type: number
required: true
description: Summary Field Id of the sheet summary field being accessed.
- $ref: '#/paths/~1contacts/parameters/0'
post:
summary: Add Image to Sheet Summary
description: Adds an image to the summary field.
operationId: add-image-summaryField
tags:
- sheetSummary
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/0'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D~1columns~1%7BcolumnId%7D~1cellimages/post/parameters/2'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows~1%7BrowId%7D~1columns~1%7BcolumnId%7D~1cellimages/post/parameters/3'
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1rows/post/parameters/2'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: object
properties:
id:
description: SummaryField Id.
type: number
index:
description: Field index or position. This number is zero-based.
type: number
title:
description: Arbitrary name, must be unique within summary.
type: string
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
locked:
description: Indicates whether the field is locked.
type: boolean
lockedForUser:
description: Indicates whether the field is locked for the
requesting user.
type: boolean
objectValue:
$ref: '#/components/schemas/Cell/properties/objectValue'
formula:
description: The formula for a cell, if set.
type: string
image:
$ref: '#/components/schemas/Cell/properties/image'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
version:
description: Sheet version number that is incremented every
time a sheet is modified.
type: number
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields/{fieldId}/images?altText=my%20image\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ image/jpeg\" \\\n-H 'Content-Disposition: attachment; filename=\"picture.jpg\"\
' \\\n-X POST \\\n--data-binary @picture.jpg\n"
- lang: C#
source: "smartsheet.SheetResources.SummaryResources.AddSheetSummaryFieldImage(\n\
\ 1421228469708676, // sheetId\n 5629723890335892, // fieldId\n\
\ \"picture.jpg\", // file\n \"image/jpeg\", // contentType\n \"\
my image\" // altText\n);\n"
- lang: Java
source: "smartsheet.sheetResources().summaryResources().addSheetSummaryFieldImage(\n\
\ 1421228469708676L, // long sheetId\n 5629723890335892L,\
\ // long fieldId\n \"picture.jpg\", // file\n \"image/jpeg\"\
, // contentType\n \"my image\" // altText\n );\n"
- lang: JavaScript
source: "var options = {\n sheetId: 1421228469708676,\n fieldId: 5629723890335892,\n\
\ path: 'C:/picture.jpg',\n fileName: 'picture.jpg'\n};\n\nsmartsheet.sheets.addSummaryFieldImage(options)\n\
\ .then(function(summary) {\n console.log(summary);\n }).catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.add_sheet_summary_field_image(\n 1421228469708676,\
\ # sheet_id\n 5629723890335892, # field_id\n \"picture.jpg\"\
, # file\n \"image/jpeg\", # file_type\n \"my image\" # alt_text\n\
)\n"
- lang: Ruby
source: "# Sample 1: Add image\nfile = File.new('C:\\picture.jpg')\nsmartsheet.sheets.summaries.add_image(\n\
\ sheet_id: 1421228469708676,\n field_id: 5629723890335892,\n file: file,\n\
\ filename: 'picture.jpg',\n file_length: file.size,\n content_type:\
\ 'image/jpeg'\n)\n\n# Sample 2: Add image from path\nsmartsheet.sheets.summaries.add_image_from_path(\n\
\ sheet_id: 1421228469708676,\n field_id: 5629723890335892,\n path: 'C:\\\
picture.jpg',\n filename: 'picture.jpg',\n content_type: 'image/jpeg'\n\
)\n"
/sheets/{sheetId}/updaterequests:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Update Requests
description: >
Gets a summarized list of all update requests that have future schedules
associated with the specified sheet.
Only the following fields are returned in the response:
* **id**
* **ccMe**
* **createdAt**
* **message**
* **modifiedAt**
* **schedule**
* **sendTo**
* **sentBy**
* **subject**
operationId: updaterequests-list
tags:
- updateRequests
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: The list of UpdateRequest objects
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of UpdateRequest objects
type: array
items:
type: object
allOf:
- $ref: '#/components/schemas/UpdateRequest/allOf/0'
- type: object
properties:
id:
description: Id of the update request.
type: number
createdAt:
description: The date and time for when this request
was originally created. Read-only.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
description: The date and time for when the last change
was made to this request. Read-only.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
schedule:
description: The schedule for which update requests
are sent out.
allOf:
- $ref: '#/components/schemas/UpdateRequest/allOf/1/properties/schedule/allOf/0'
sentBy:
description: >
`User` object containing `name` and `email`
of the sender.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
x-codeSamples:
- lang: cURL
source: "# Example request: list update requests\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "# Example request: list update requests\n\nPaginatedResult\
\ results = smartsheet.SheetResources.UpdateRequestResources.ListUpdateRequests(\n\
\ 1639534409607044, // sheetId\n null //\
\ PaginationParameters\n);\n"
- lang: Java
source: "# Example request: list update requests\n\nPagedResult\
\ results = smartsheet.sheetResources().updateRequestResources().listUpdateRequests(\n\
\ 1639534409607044L, // long sheetId\n null \
\ // PaginationParameters\n);"
- lang: JavaScript
source: "# Example request: list update requests\n\n// Set options\nvar options\
\ = {\n sheetId: 1639534409607044\n};\n\n// List update requests\nsmartsheet.sheets.getAllUpdateRequests(options)\n\
\ .then(function(requestsList) {\n console.log(requestsList);\n\
\ })\n .catch(function(error) {\n console.log(error);\n \
\ });"
label: Node.js
- lang: Python
source: "# Example request: list update requests\n\nresponse = smartsheet_client.Sheets.list_update_requests(5190835902932868)\
\ # sheet_id\nupdate_requests = response.data"
- lang: Ruby
source: "# Example request: list update requests\n\nresponse = smartsheet.update_requests.list(\n\
\ sheet_id: 3294745817573252\n)\nupdate_requests = response[:data]"
post:
summary: Create an Update Request
description: >
Creates an update request for the specified rows within the sheet. An
email notification (containing a link to the update request) is sent to
the specified recipients according to the specified schedule.
The recipients of an update request must be specified by using email addresses
only. Sending an update request to a group is not supported.
The following attributes have the following values when not specified:
* **ccMe:** false
* **message:** Please update the following rows in my online sheet.
* **subject:** Update Request: {Sheet Name}
When the Schedule object is not specified, the request is sent to the recipients
immediately.
If an error occurs because the request specified one or more *alternate email
addresses*,
please retry using the primary email address.
operationId: updaterequests-create
tags:
- updateRequests
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1updaterequests/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
responses:
'200':
description: Result object containing the newly created UpdateRequest object.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1updaterequests/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
x-codeSamples:
- lang: cURL
source: "# Example request: create update request\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\n \"sendTo\": [\n {\"email\"\
: \"recipient1@smartsheet.com\"},\n {\"email\": \"recipient2@smartsheet.com\"\
}\n ],\n \"subject\": \"Sample Monthly Update Request\",\n \"message\"\
: \"Please update my online sheet.\",\n \"ccMe\": false,\n \"rowIds\"\
: [4508292249610116, 2256492435924868],\n \"columnIds\": [4508284196546436,\
\ 2256484382861188],\n \"includeAttachments\": false,\n \"includeDiscussions\"\
: false\n}'"
- lang: C#
source: "# Example request: create update request\n\n// Specify recipients\n\
Recipient[] recipientSpecification = new Recipient[] {\n new Recipient\
\ { Email = \"recipient1@smartsheet.com\"}\n};\n\n// Configure update request\n\
UpdateRequest updateRequestSpecification = new UpdateRequest\n{\n SendTo\
\ = recipientSpecification,\n Subject = \"Sample Monthly Update Request\"\
,\n Message = \"Please update my online sheet.\",\n CcMe = true,\n\
\ RowIds = new long[] { 1123834706323332, 5627434333693828 },\n ColumnIds\
\ = new long[] { 4549065498224516, 2297265684539268 },\n IncludeAttachments\
\ = true,\n IncludeDiscussions = true\n};\n\n// Send update request via\
\ email\nUpdateRequest newUpdateRequest = smartsheet.SheetResources.UpdateRequestResources.CreateUpdateRequest(\n\
\ 3285357287499652, // sheetId\n updateRequestSpecification\n\
);"
- lang: Java
source: "# Example request: create update request\n\n// Specify recipients\n\
RecipientEmail recipientA = new RecipientEmail()\n .setEmail(\"recipient1@smartsheet.com\"\
);\n\nRecipientEmail recipientB = new RecipientEmail()\n .setEmail(\"\
recipient2@smartsheet.com\");\n\nList recipients = Arrays.asList(recipientA,\
\ recipientB);\n\n// Specify parameters for update request\nUpdateRequest\
\ updateRequest = new UpdateRequest();\nupdateRequest.setRowIds((Arrays.asList(3344087179913092L,\
\ 7847686807283588L));\nupdateRequest.setSendTo(recipients)\n .setSubject(\"\
Sample Monthly Update Request\")\n .setMessage(\"Please update my online\
\ sheet.\")\n .setColumnIds(Arrays.asList(1735559124150148L, 1735559124150148L))\n\
\ .setIncludeAttachments(false)\n .setIncludeDiscussions(false);\n\
\n// Create update request\nsmartsheet.sheetResources().updateRequestResources().createUpdateRequest(\n\
\ 1639534409607044L, // long sheetId\n updateRequest\n);"
- lang: JavaScript
source: "# Example request: create update request\n\n// Set body\nvar body\
\ = {\n rowIds: [\n 1049041315358596,\n 5552640942729092\n ],\n\
\ includeAttachments: true,\n includeDiscussions: false,\n sendTo: [\n\
\ {\n email: \"jane.roe@smartsheet.com\"\n }\n ],\n subject:\
\ \"Sample Monthly Update Request\",\n message: \"Please update my online\
\ sheet.\",\n schedule: {\n type: \"DAILY\",\n startAt: \"2016-04-01T00:00:00Z\"\
,\n endAt: \"2018-12-31T00:00:00Z\",\n dayDescriptors: [\n \"\
WEEKDAY\"\n ]\n }\n};\n\n// Set options\nvar options = {\n sheetId:\
\ 1696801624483716,\n body: body\n};\n\n// Create update request\nsmartsheet.sheets.createUpdateRequest(options)\n\
\ .then(function(updatedRequest) {\n console.log(updatedRequest);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "# Example request: create update request\n\n# Configure update request\n\
request = smartsheet.models.UpdateRequest()\nrequest.send_to = [{'email':\
\ 'someone@smartsheet.com'}]\nrequest.subject = 'Please update based on\
\ meeting'\nrequest.message = 'Hello, please checkout my update request'\n\
request.cc_me = False\nrequest.include_discussions = False\nrequest.include_attachments\
\ = False\nrequest.row_ids = [6809535313667972]\nrequest.column_ids = [7036894123976580]\n\
\n# Send update request\naction = smartsheet_client.Sheets.create_update_request(\n\
\ 5190835902932868, # sheet_id\n request\n)"
- lang: Ruby
source: "# Example request: create update request\n\nbody = {\n send_to:\
\ [\n {\n email: 'jane.roe@smartsheet.com'\n }\n ],\n row_ids:\
\ [\n 7886095586224004,\n 2661640373069700\n ],\n column_ids: [\n\
\ 6962516556310404,\n 3584816835782532\n ],\n include_attachments:\
\ true,\n include_discussions: true,\n layout: 'VERTICAL',\n subject:\
\ 'Sample Monthly Update Request',\n message: 'Please update my online\
\ sheet.',\n cc_me: false,\n schedule: {\n type: 'MONTHLY',\n start_at:\
\ '2016-04-01T19:00:00Z',\n end_at: '2016-12-31T07:00:00Z',\n day_descriptors:\
\ [\n 'WEEKDAY'\n ]\n }\n}\n\nnew_update_request = smartsheet.update_requests.create(\n\
\ sheet_id: 7820135625975684,\n body: body\n)"
/sheets/{sheetId}/updaterequests/{updateRequestId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- name: updateRequestId
in: path
required: true
description: ID of the Update Request
schema:
type: string
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get an Update Request
description: >
Gets the specified update request for the sheet that has a future
schedule.
The rowIds and columnIds in the returned UpdateRequest object represent the
list at the time
the update request was created or last modified. The lists may contain Ids
of rows or columns
that are no longer valid (for example, they have been removed from the sheet).
operationId: updaterequests-get
tags:
- updateRequests
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: UpdateRequest object
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1updaterequests/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
x-codeSamples:
- lang: cURL
source: "# Example request: get update request\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests/{updateRequestId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "# Example request: get update request\n\nUpdateRequest results =\
\ smartsheet.SheetResources.UpdateRequestResources.GetUpdateRequest(\n \
\ 3285357287499652, // sheetId\n 2409350321989508 // updateRequestId\n\
);"
- lang: Java
source: "# Example request: get update request\n\nUpdateRequest results =\
\ smartsheet.sheetResources().updateRequestResources().getUpdateRequest(\n\
\ 1639534409607044L, // long sheetId\n 965780272637828L \
\ // long updateRequestId\n);"
- lang: JavaScript
source: "# Example request: get update request\n\n// Set options\nvar options\
\ = {\n sheetId: 3285357287499652,\n updateRequestId: 2409350321989508\n\
};\n\n// Get update request\nsmartsheet.sheets.getUpdateRequest(options)\n\
\ .then(function(updateRequest) {\n console.log(updateRequest);\n\
\ })\n .catch(function(error) {\n console.log(error);\n \
\ });"
label: Node.js
- lang: Python
source: "# Example request: get update request\n\nresponse = smartsheet_client.Sheets.get_update_request(\n\
\ 5190835902932868, # sheet_id\n 7510551698925444 # update_request_id\n\
)"
- lang: Ruby
source: "# Example request: get update request\n\nupdate_request = smartsheet.update_requests.get(\n\
\ sheet_id: 3294745817573252,\n update_request_id: 4523799765903236\n\
) = response[:data]"
put:
summary: Update an Update Request
description: >
Changes the specified update request for the sheet.
**Making changes to update requests that do not have future scheduled delivery
is not allowed.**
The UpdateRequest object in the request body must specify one or more of the
following attributes:
* **ccMe:** Boolean
* **columnIds:** number[]
* **includeAttachments:** Boolean
* **includeDiscussions:** Boolean
* **message:** string
* **schedule:** Schedule object
* **sendTo:** Recipient[]
* **subject:** string
If an error occurs because the request specified one or more *alternate email
addresses*,
please retry using the primary email address.
operationId: updaterequests-update
tags:
- updateRequests
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
responses:
'200':
description: Result object containing the modified UpdateRequest object
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1updaterequests~1%7BupdateRequestId%7D/get/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "# Example request: change update request\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests/{updateRequestId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{ \n \"subject\": \"Sample Monthly\
\ Update Request\", \n \"message\": \"Please update my online sheet.\"\n\
}'\n"
- lang: C#
source: "# Example request: change update request\n\n// Identify the update\
\ request you want to change\nUpdateRequest updateRequestSpecification =\
\ new UpdateRequest\n{\n Id = 7178482007467908, // long updateRequestId\n\
\ Subject = \"Sample Monthly Update Request\",\n Message = \"Please\
\ update my online sheet.\"\n};\n\n// Change update request\nUpdateRequest\
\ updatedUpdateRequest = smartsheet.SheetResources.UpdateRequestResources.UpdateUpdateRequest(\n\
\ 3285357287499652, // sheetId\n updateRequestSpecification\n\
);"
- lang: Java
source: "Example request: change update request\n\nUpdateRequest updateRequest\
\ = new UpdateRequest();\nupdateRequest.setId(3294745817573252L);\nupdateRequest.setColumnIds(Arrays.asList(1735559124150148L,\
\ 1735559124150148L));\nupdateRequest.setIncludeAttachments(true);\nsmartsheet.sheetResources().updateRequestResources().updateUpdateRequest(\n\
\ 3294745817573252L, // long sheetId\n updateRequest\n);\n"
- lang: JavaScript
source: "# Example request: change update request\n\n// Set text\nvar body\
\ = {\n subject: \"Sample Monthly Update Request\"\n};\n\n// Set options\n\
var options = {\n sheetId: 3285357287499652,\n updateRequestId: 7178482007467908,\n\
\ body: body\n};\n\n// Change update request\nsmartsheet.sheets.changeUpdateRequest(options)\n\
\ .then(function(updatedRequest) {\n console.log(updatedRequest);\n\
\ })\n .catch(function(error) {\n console.log(error);\n \
\ });"
label: Node.js
- lang: Python
source: "# Example request: change update request\n\n# Update required request\
\ fields\nrequest = smartsheet.models.UpdateRequest()\nrequest.subject =\
\ 'Sample Monthly Update Request'\nrequest.column_ids = [7036894123976580]\n\
request.include_attachments = True\n\n# Change update request\naction =\
\ smartsheet_client.Sheets.update_update_request(\n 3294745817573252,\
\ # sheet_id\n 7820135625975684, # update_request_id\n \
\ request\n)"
- lang: Ruby
source: "# Example request: change update request\n\nbody = {\n send_to:\
\ [\n {\n email: 'jane.roe@smartsheet.com'\n }\n ],\n column_ids:\
\ [\n 6962516556310404,\n 3584816835782532\n ],\n include_attachments:\
\ false,\n include_discussions: false,\n subject: 'Sample Monthly Update\
\ Request',\n message: \"Please update my online sheet.\",\n cc_me: false,\n\
\ schedule: {\n type: 'MONTHLY',\n start_at: '2016-04-01T19:00:00Z',\n\
\ end_at: '2016-12-31T07:00:00Z',\n day_ordinal: 'SECOND',\n day_descriptors:\
\ [\n 'THURSDAY'\n ],\n repeat_every: 2\n }\n}\n\nupdate_request\
\ = smartsheet.update_requests.update(\n sheet_id: 3294745817573252,\n\
\ update_request_id: 7820135625975684,\n body: body\n)"
delete:
summary: Delete an Update Request
description: >
Terminates the future scheduled delivery of the update request specified
in the URL.
operationId: updaterequests-delete
tags:
- updateRequests
security:
- APIToken: []
- OAuth2:
- ADMIN_SHEETS
- WRITE_SHEETS
responses:
'200':
description: Result object
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1updaterequests~1%7BupdateRequestId%7D/put/responses/200/content/application~1json/schema/allOf/0'
x-codeSamples:
- lang: cURL
source: "# Example request: delete update request\n\ncurl https://api.smartsheet.com/2.0/sheets/{sheetId}/updaterequests/{updateRequestId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE"
- lang: C#
source: "# Example request: delete update request\n\nsmartsheet.SheetResources.UpdateRequestResources.DeleteUpdateRequest(\n\
\ 3285357287499652, // sheetId\n 2409350321989508 // updateRequestId\n\
);"
- lang: Java
source: "# Example request: delete update request\n\nsmartsheet.sheetResources().updateRequestResources().deleteUpdateRequest(\n\
\ 1639534409607044L, // long sheetId\n 965780272637828L \
\ // long updateRequestId\n);"
- lang: JavaScript
source: "# Example request: delete update request\n\n// Set options\nvar options\
\ = {\n sheetId: 3285357287499652,\n updateRequestId: 2409350321989508\n\
};\n\n// Delete update request\nsmartsheet.sheets.deleteUpdateRequest(options)\n\
\ .then(function(result) {\n console.log(result);\n })\n \
\ .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "# Example request: delete update request\n\nsmartsheet_client.Sheets.delete_update_request(\n\
\ 5190835902932868, # sheet_id\n 7444581001258884 #\
\ update_request_id\n)"
- lang: Ruby
source: "# Example request: delete update request\n\nsmartsheet.update_requests.delete(\n\
\ sheet_id: 3294745817573252,\n update_request_id: 4523799765903236\n\
)"
/sheets/{sheetId}/shares:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
post:
summary: Share Sheet
description: Shares a sheet with the specified users and groups.
operationId: share-sheet
tags:
- sharing
- sheets
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
parameters:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/parameters/0'
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
- type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: >
Result object containing either a single Share object or an array of
Share objects, corresponding to what
was specified in the request. All shares have scope=ITEM.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
- type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
'400':
description: >
If called with a single Share object, and that user or group share
already exists, error code 1025 is returned.
If called with an array of Share objects, and one or more user or group
shares in the array already exist,
they are ignored and omitted from the response.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares/post/responses/400/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/shares?sendEmail=true'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{\"email\": \"jane.doe@smartsheet.com\"\
, \"accessLevel\": \"EDITOR\"}]'\n"
- lang: C#
source: "// Specify share (to one user as Editor)\nShare[] shareSpecification\
\ = new Share[] { new Share\n {\n Email = \"jane.doe@smartsheet.com\"\
,\n AccessLevel = AccessLevel.EDITOR\n }\n};\n\n// Share sheet\nIList\
\ addressList = smartsheet.SheetResources.ShareResources.ShareTo(\n 4583614634583940,\
\ // sheetId\n shareSpecification,\n true \
\ // Nullable sendEmail\n);\n"
- lang: Java
source: "// Specify share (to one user as Editor)\nShare shareSpecification\
\ = new Share()\n .setEmail(\"jane.doe@smartsheet.com\")\n \
\ .setAccessLevel(AccessLevel.EDITOR);\n\n// Share sheet\nList addressList\
\ = smartsheet.sheetResources().shareResources().shareTo(\n 4583614634583940L,\
\ // long sheetId\n (Arrays.asList(shareSpecification)),\n\
\ true // Boolean sendEmail\n \
\ );\n"
- lang: JavaScript
source: "// Specify share (to one user as Editor)\nvar share = [\n\t{\n\t\t\
\"email\": \"jane.doe@smartsheet.com\",\n\t\t\"accessLevel\": \"EDITOR\"\
\n\t}\n];\n\n// Set options\nvar options = {\n sheetId: 4583614634583940,\n\
\ body: share\n };\n\n// Share sheet\nsmartsheet.sheets.share(options)\n\
\ .then(function(addressList) {\n console.log(addressList);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.share_sheet(\n 4583614634583940,\
\ # sheet_id\n smartsheet.models.Share({\n 'access_level': 'EDITOR',\n\
\ 'email': 'jane.doe@smartsheet.com'\n }),\n True \
\ # sendEmail\n)\n"
- lang: Ruby
source: "body = {\n email: 'jane.doe@smartsheet.com',\n access_level: 'EDITOR',\n\
\ subject: 'This sheet has been shared with you!',\n message: 'This Smartsheet\
\ is ready for your inspection.'\n}\n\nresponse = smartsheet.sheets.share.create(\n\
\ sheet_id: 4583173393803140,\n body: body\n)\n"
get:
summary: List Sheet Shares
description: >
Gets a list of all users and groups to whom the specified Sheet is
shared, and their access level. This operation
supports query string parameters for pagination of results. For more information,
see Paging Query String Parameters.
operationId: list-sheet-shares
tags:
- sharing
- sheets
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: >
IndexResult object containing an array of Share objects. By default,
this operation returns only item-level
shares (scope=ITEM). Use the sharingInclude parameter to request that
workspace-level shares
(scope=WORKSPACE) also be returned.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares/post/responses/400/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult shares = smartsheet.SheetResources.ShareResources.ListShares(\n\
\ 4583614634583940, // sheetId\n null \
\ // PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult shares = smartsheet.sheetResources().shareResources().listShares(\n\
\ 4583614634583940L, // long sheetId\n null, \
\ // PaginationParameters\n true \
\ // Boolean includeWorkspaceShares\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 4583614634583940\n};\n\
\n// List sheet shares\nsmartsheet.sheets.listShares(options)\n .then(function(shareList)\
\ {\n console.log(shareList);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Sheets.list_shares(\n\
\ 4583614634583940, # sheet_id\n include_all=True)\nshares = response.data\n\
\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Sheets.list_shares(\n\
\ 4583614634583940, # sheet_id\n page_size=10,\n page=1)\npages\
\ = response.total_pages\nshares = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.share.list(\n sheet_id: 4583173393803140\n\
)\nshares = response[:data]\n"
/sheets/{sheetId}/shares/{shareId}:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares~1%7BshareId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Sheet Share.
description: Gets the share specified in the URL.
operationId: share-sheet-get
tags:
- sharing
- sheets
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: Returns Share object.
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Share share = smartsheet.SheetResources.ShareResources.GetShare(\n\
\ 4583614634583940, // sheetId\n \"AQAISF82FOeE\" \
\ // string shareId\n);\n"
- lang: Java
source: "Share share = smartsheet.sheetResources().shareResources().getShare(\n\
\ 4583614634583940L, // long sheetId\n \"AAAASuWWFOeE\"\
\ // string shareId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 4583614634583940,\n \
\ shareId: \"AQAISF82FOeE\"\n};\n\n// Get sheet share\nsmartsheet.sheets.getShare(options)\n\
\ .then(function(share) {\n console.log(share);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "share = smartsheet_client.Sheets.get_share(\n 4583614634583940,\
\ # sheet_id\n 'AAAASuWWFOeE') # share_id\n"
- lang: Ruby
source: "share = smartsheet.sheets.share.get(\n sheet_id: 4583173393803140,\n\
\ share_id: 'AAABbMomFOeE'\n)\n"
delete:
summary: Delete Sheet Share
description: Deletes the share specified in the URL.
operationId: delete-sheet-share
tags:
- sharing
- sheets
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
responses:
'200':
description: Returns Result object.
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares~1%7BshareId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.SheetResources.ShareResources.DeleteShare(\n 4583614634583940,\
\ // sheetId\n \"AAAASuWWFOeE\" // string\
\ shareId\n);\n"
- lang: Java
source: "smartsheet.sheetResources().shareResources().deleteShare(\n \
\ 4583614634583940L, // long sheetId\n \"AAAASuWWFOeE\" \
\ // string shareId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 4583614634583940,\n \
\ shareId: \"AAAASuWWFOeE\"\n};\n\n// Delete sheet share\nsmartsheet.sheets.deleteShare(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sheets.delete_share(\n 4583614634583940, \
\ # sheet_id\n 'AAAFeF82FOeE') # share_id\n"
- lang: Ruby
source: "smartsheet.sheets.share.delete(\n sheet_id: 4583173393803140,\n\
\ share_id: 'AAABbMomFOeE'\n)\n"
put:
summary: Update Sheet Share.
description: Updates the access level of a user or group for the specified sheet.
operationId: update-sheet-share
tags:
- sharing
- sheets
security:
- APIToken: []
- OAuth2:
- SHARE_SHEETS
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares~1%7BshareId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: object
items:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares~1%7BshareId%7D/get/responses/200/content/application~1json/schema'
responses:
'200':
description: >
By default, this operation returns only item-level shares
(scope=ITEM). Use the include parameter
to request that workspace-level shares (scope=WORKSPACE) also be returned.
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares~1%7BshareId%7D/delete/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1shares~1%7BshareId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{\"accessLevel\": \"VIEWER\"}'\n"
- lang: C#
source: "// Set the access level to Viewer\nShare shareSpecification = new\
\ Share\n{\n Id = \"AAAFeF82FOeE\",\n AccessLevel = AccessLevel.VIEWER\n\
};\n\n// Update sheet share\nShare updatedShare = smartsheet.SheetResources.ShareResources.UpdateShare(\n\
\ 4583614634583940, // sheetId\n shareSpecification\n);\n"
- lang: Java
source: "// Set the access level to Viewer\nShare shareSpecification = new\
\ Share()\n .setEmail(\"jane.doe@smartsheet.com\")\n .setAccessLevel(AccessLevel.EDITOR);\n\
\n// Update sheet share\nShare updatedShare = smartsheet.sheetResources().shareResources().updateShare(\n\
\ 4583614634583940L, // long sheetId\n shareSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Set access level to Viewer\nvar shareSpecification = {\"accessLevel\"\
: \"VIEWER\"};\n\n// Set options\nvar options = {\n sheetId: 1696801624483716,\n\
\ shareId: \"AAAHAYImFOeE\",\n body: shareSpecification\n};\n\n// Update\
\ sheet share\nsmartsheet.sheets.updateShare(options)\n .then(function(updatedShare)\
\ {\n console.log(updatedShare);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_share = smartsheet_client.Sheets.update_share(\n 4583614634583940,\
\ # sheet_id\n 'AAAFeF82FOeE', # share_id\n smartsheet.models.Share({\n\
\ 'access_level': 'VIEWER'\n })\n)\n"
- lang: Ruby
source: "body = {\n access_level: 'VIEWER'\n}\n\nresponse = smartsheet.sheets.share.update(\n\
\ sheet_id: 4583173393803140,\n share_id: 'AAABbMomFOeE',\n body: body\n\
)\n"
/sheets/{sheetId}/sort:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1favorites/post/parameters/0'
post:
summary: Sort Rows in Sheet
description: Sorts the rows of a sheet, either in ascending or descending order.
operationId: rows-sort
tags:
- rows
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- name: include&exclude
in: query
required: false
description: >
(Optional) Any of the relevant parameters or query parameters listed
for [Get Sheet](../../tag/sheets#operation/getSheet).
schema:
type: string
requestBody:
description: >
[SortSpecifier](../../tag/sheetsObjects#section/SortSpecifier-Object)
with the following attribute:
* **sortCriteria** -- [SortCriterion](../../tag/sheetsObjects#section/SortCriterion-Object)
array in priority order. Specifies sort order.
content:
application/json:
schema:
type: object
properties:
sortCriteria:
description: Specifies sort order. Array is in priority order.
type: array
items:
$ref: '#/components/schemas/SortSpecifier/properties/sortCriteria/items'
responses:
'200':
description: Returns [Sheet object](../../tag/sheetsObjects#section/Sheet-Object),
populated according to the specified parameters.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Folder/properties/sheets/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/sort \\\n-H\
\ \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"sortCriteria\": [{\"columnId\"\
: 4583173393803140, \"direction\": \"DESCENDING\"}]}'\n"
- lang: C#
source: "SortCriterion criterion = new SortCriterion\n{\n ColumnId = 4583173393803140,\
\ // columnId\n Direction = SortDirection.DESCENDING\n};\nSortSpecifier\
\ specifier = new SortSpecifier\n{\n SortCriteria = new SortCriterion[]\
\ { criterion }\n};\n\nSheet sheet = smartsheet.SheetResources.SortSheet(\n\
\ 4583173393803140, // sheetId\n specifier\n );\n"
- lang: Java
source: "SortCriterion criterion = new SortCriterion();\ncriterion.setColumnId(4583173393803140L);\
\ // long columnId\ncriterion.setDirection(SortDirection.DESCENDING);\n\
SortSpecifier specifier = new SortSpecifier();\nspecifier.setSortCriteria(Arrays.asList(criterion));\n\
\nSheet sheet = smartsheet.sheetResources().sortSheet(\n 4583173393803140L,\
\ // long sheetId\n specifier\n );\n"
- lang: JavaScript
source: "// Specify sort criteria\nvar body = {\n sortCriteria: [\n {\n\
\ columnId: 4583173393803140,\n direction: \"DESCENDING\"\n \
\ }\n ]\n};\n\n// Sort rows\nsmartsheet.sheets.sortRowsInSheet({sheetId:\
\ 9283173393803140, body: body})\n .then((result) => {\n console.log(\"\
success\");\n console.log(JSON.stringify(result));\n })\n .catch((error)\
\ => {\n console.log(\"error\");\n console.log(JSON.stringify(error));\n\
\ });\n"
label: Node.js
- lang: Python
source: "sort_specifier = smartsheet.models.SortSpecifier({\n 'sort_criteria':\
\ [smartsheet.models.SortCriterion({\n 'column_id': 4583173393803140,\n\
\ 'direction': 'DESCENDING'\n })]\n})\nsheet = smartsheet_client.Sheets.sort_sheet(9283173393803140,\
\ sort_specifier)\n"
- lang: Ruby
source: "smartsheet.sheets.rows.sort(\n sheet_id: 9283173393803140,\n body:\
\ {\n sort_criteria: [\n {\n column_id: 4583173393803140,\n\
\ direction: 'DESCENDING'\n }\n ]\n }\n)\n"
/sheets/{sheetId}/version:
parameters:
- $ref: '#/paths/~1search~1sheets~1%7BsheetId%7D/parameters/0'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Sheet Version
description: |
Gets the sheet version without loading the entire sheet.
The following actions increment sheet version:
* add/modify cell value
* add/modify discussion/comment
* add/modify row
* add/remove/update version attachment
* cell updated via cell link
* change formatting
operationId: get-sheetVersion
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D/get/responses/200/content/application~1json/schema/oneOf/1'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sheets/{sheetId}/version \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Integer version = smartsheet.SheetResources.GetSheetVersion(\n 1531988831168388\
\ // sheetId\n);\n"
- lang: Java
source: "Integer version = smartsheet.sheetResources().getSheetVersion(\n\
\ 1531988831168388L // long sheetId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sheetId: 1531988831168388\n};\n\
\n// Get sheet version\nsmartsheet.sheets.getSheetVersion(options)\n .then(function(version)\
\ {\n console.log(version);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "version = smartsheet_client.Sheets.get_sheet_version(\n 1531988831168388)\
\ # sheet_id\n"
- lang: Ruby
source: "version = smartsheet.sheets.get_version(\n sheet_id: 1531988831168388\n\
)\n"
/sights:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
operationId: list-sights
summary: List Dashboards
description: Gets a list of all dashboards that the user has access to.
tags:
- dashboards
security:
- APIToken: []
- OAuth2:
- READ_SIGHTS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/1'
- $ref: '#/paths/~1contacts/get/parameters/2'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: >
IndexResult object containing an array of Dashboard objects with a
subset of attributes.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: List of Dashboards
type: array
items:
type: object
allOf:
- type: object
allOf:
- type: object
properties:
name:
description: Dashboard name.
type: string
properties:
id:
description: Dashboard Id.
type: number
readOnly: true
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
permalink:
description: URL that represents a direct link to the
dashboard in Smartsheet.
type: string
readOnly: true
properties:
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "PaginatedResult sights = smartsheet.SightResources.ListSights(\n\
\ null, // PaginationParameters\n null // Nullable\
\ modifiedSince\n);\n"
- lang: Java
source: "PagedResult sights = smartsheet.sightResources().listSights(\n\
\ null, // PaginationParameters\n null // Date\
\ modifiedSince\n );\n"
- lang: JavaScript
source: "smartsheet.sights.listSights()\n .then(function(sights) {\n console.log(sights.data);\n\
\ })\n .catch(function(error) {\n console.log(error);\n })\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sights.list_sights(include_all=True)\n\
sights = response.data\n"
- lang: Ruby
source: "response = smartsheet.sights.list\nsights = response[:data]\n"
/sights/{sightId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: sightId
in: path
required: true
description: SightID of the sight being accessed.
schema:
type: string
get:
summary: Get Dashboard
description: Gets the specified dashboard.
operationId: get-sight
parameters:
- name: include
in: query
required: false
description: >
A comma-separated list of optional elements to include in the
response:
* **objectValue** - when used in combination with a **level** query parameter,
includes the email addresses for multi-contact data.
* **source** - the Source object for any Sight that was created from another
Sight, if any
schema:
type: string
enum:
- objectValue
- source
- name: level
in: query
required: false
description: Specifies whether new functionality, such as multi-contact data
is returned in a backwards-compatible, text format (**level=0**, default),
multi-contact data (**level=2**), multi-picklist data (**level=3**), or
Metric widget with sheet summary (**level=4**).
schema:
type: integer
default: 0
- $ref: '#/paths/~1contacts/get/parameters/2'
tags:
- dashboards
security:
- APIToken: []
- OAuth2:
- READ_SIGHTS
responses:
'200':
description: Dashboard object
content:
application/json:
schema:
$ref: '#/components/schemas/Folder/properties/sights/items'
default:
description: Generic Error Payload
content:
application/json:
schema: {}
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}?level=4 \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Sight sight = smartsheet.SightResources.GetSight(\n 6327127650920324\
\ // long sightId\n);\n"
- lang: Java
source: "Sight sight = smartsheet.sightResources().getSight(\n 6327127650920324L\
\ // long sightId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sightId: 6327127650920324\n};\n\
\n// Get dashboard\nsmartsheet.sights.getSight(options)\n .then(function(sight)\
\ {\n console.log(sight);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "sight = smartsheet_client.Sights.get_sight(\n 6327127650920324)\
\ # sightId\n"
- lang: Ruby
source: "sight = smartsheet.sights.get(\n sight_id: 6327127650920324\n)\n"
put:
summary: Update Dashboard
description: Updates (renames) the specified dashboard.
operationId: update-sight
parameters:
- $ref: '#/paths/~1contacts/get/parameters/2'
- $ref: '#/paths/~1favorites/post/parameters/0'
tags:
- dashboards
security:
- APIToken: []
- OAuth2:
- ADMIN_SIGHTS
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
description: Dashboard name.
type: string
responses:
'200':
description: Result object containing the updated Dashboard object.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1publish/put/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1sights~1%7BsightId%7D/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema: {}
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X PUT \\\n-d '{\"name\": \"New Dashboard Name\"}'\n"
- lang: C#
source: "Sight sight = smartsheet.SightResources.UpdateSight(\n new Sight\
\ {\n Id = 5363568917931908, // sightId\n Name = \"New Dashboard\
\ Name\"\n }\n);\n"
- lang: Java
source: "Sight sight = new Sight();\nsight.setId(5363568917931908L); //\
\ long sightId\nsight.setName(\"New Dashboard Name\");\nSight updatedSight\
\ = smartsheet.sightResources().updateSight(sight);\n"
- lang: JavaScript
source: "// Set property to change\nvar body = {\n name: \"New Dashboard\
\ Name\"\n};\n\n// Set options\nvar options = {\n sightId: 5363568917931908,\n\
\ body: body\n};\n\n// Update Dashboard\nsmartsheet.sights.updateSight(options)\n\
\ .then(function(updatedSight) {\n console.log(updatedSight);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_sight = smartsheet_client.Sights.update_sight(\n 5363568917931908,\
\ # sight_id\n smartsheet.models.Sight({\n 'name': 'New Dashboard\
\ Name'\n })\n)\n"
- lang: Ruby
source: "# Specify property to change\nbody = {\n name: 'New Dashboard Name'\n\
}\n\n# Update Dashboard\nresponse = smartsheet.sights.update(\n sight_id:\
\ 5363568917931908,\n body: body\n)\nupdated_sight = response[:result]\n"
delete:
summary: Delete Dashboard
description: Deletes the dashboard specified in the URL.
operationId: delete-sight
tags:
- dashboards
security:
- APIToken: []
- OAuth2:
- DELETE_SIGHTS
responses:
'200':
description: Generic response result
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema: {}
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n"
- lang: C#
source: "smartsheet.SightResources.DeleteSight(\n 5077532685952900 \
\ // sightId\n);\n"
- lang: Java
source: "smartsheet.sightResources().deleteSight(\n 3100061023397764L\
\ // long sightId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sightId: 5363568917931908\n};\n\
\n// Delete Dashboard\nsmartsheet.sights.deleteSight(options)\n .then(function(results)\
\ {\n console.log(results);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sights.delete_sight(3404239197235076) # sight_id\n"
- lang: Ruby
source: "smartsheet.sights.delete(\n sight_id: 6327127650920324\n)\n"
/sights/{sightId}/copy:
post:
summary: Copy Dashboard
description: Creates a copy of the specified dashboard.
operationId: copy-sight
tags:
- dashboards
security:
- APIToken: []
- OAuth2:
- CREATE_SIGHTS
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1sights~1%7BsightId%7D/parameters/1'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: >
Result object containing a dashboard with a subset of attributes for
the newly created dashboard.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1publish/put/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: object
allOf:
- type: object
properties:
name:
description: Dashboard name.
type: string
properties:
id:
description: Dashboard Id.
type: number
readOnly: true
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
permalink:
description: URL that represents a direct link to the dashboard
in Smartsheet.
type: string
readOnly: true
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}/copy \\\n-H\
\ \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\"\n-d '{\n \"destinationType\": \"workspace\",\n \"\
destinationId\": 7960873114331012,\n \"newName\": \"newDashboardName\"\n\
}' \\\n-X POST\n"
- lang: C#
source: "// Specify destination\nContainerDestination destination = new ContainerDestination\n\
{\n DestinationId = 3791509922310020, // long destinationFolderId\n\
\ DestinationType = DestinationType.FOLDER,\n NewName = \"newDashboardName\"\
\n};\n\n// Copy Dashboard\nSight sight = smartsheet.SightResources.CopySight(\n\
\ 6327127650920324, // long sightId\n destination\n\
);\n"
- lang: Java
source: "// Specify destination\nContainerDestination destination = new ContainerDestination()\n\
\ .setDestinationType(DestinationType.FOLDER)\n .setDestinationId(3791509922310020L)\n\
\ .setNewName(\"newDashboardName\");\n\n// Copy Dashboard\nSight\
\ sight = smartsheet.sightResources().copySight(\n 6327127650920324L,\
\ // long sightId\n destination\n \
\ );\n"
- lang: JavaScript
source: "// Specify new dashboard properties\nvar body = {\n destinationType:\
\ \"home\",\n newName: \"newDashboardName\"\n};\n\n// Set options\nvar\
\ options = {\n sightId: 6327127650920324,\n body: body\n};\n\n// Copy\
\ Dashboard\nsmartsheet.sights.copySight(options)\n .then(function(copiedSight)\
\ {\n console.log(copiedSight);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "new_sight = smartsheet_client.Sights.copy_sight(\n 6327127650920324,\
\ # sight_id\n smartsheet.models.ContainerDestination({\n\
\ 'destination_type': 'folder', # folder, workspace, or home\n\
\ 'destination_id': 3791509922310020, # folder_id\n 'new_name':\
\ 'newDashboardName'\n })\n)\n"
- lang: Ruby
source: "# Specify destination\nbody = {\n destination_type: 'folder',\n\
\ destination_id: 3791509922310020,\n new_name: 'newDashboardName'\n}\n\
\n# Copy Dashboard\nnew_sight = smartsheet.sights.copy(\n sight_id: 6327127650920324,\n\
\ body: body\n)\n"
/sights/{sightId}/move:
post:
summary: Move Dashboard
description: Moves the specified dashboard to a new location.
operationId: move-sight
tags:
- dashboards
security:
- APIToken: []
- OAuth2:
- CREATE_SIGHTS
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1sights~1%7BsightId%7D/parameters/1'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: >
Result object containing a Dashboard object with a subset of
attributes for the moved dashboard.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1publish/put/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1sights~1%7BsightId%7D~1copy/post/responses/200/content/application~1json/schema/allOf/1/properties/result'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}/move \\\n-H\
\ \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\"\n-d '{\n \"destinationType\": \"folder\",\n \"destinationId\"\
: workspace_or_folder_id\n}' \\\n-X POST\n"
- lang: C#
source: "// Specify destination\nContainerDestination destination = new ContainerDestination\n\
{\n DestinationId = 8460057768683396, // long destinationFolderId\n\
\ DestinationType = DestinationType.FOLDER\n};\n\n// Move Dashboard\nSight\
\ sight = smartsheet.SightResources.MoveSight(\n 5077532685952900, \
\ // long sightId\n destination\n);\n"
- lang: Java
source: "// Specify destination\nContainerDestination destination = new ContainerDestination()\n\
\ .setDestinationType(DestinationType.FOLDER)\n .setDestinationId(7960873114331012L);\n\
\n// Move Dashboard\nSight sight = smartsheet.sightResources().moveSight(\n\
\ 4583173393803140L, // long sightId\n \
\ destination\n );\n"
- lang: JavaScript
source: "// Set destination\nvar body = {\n destinationType: \"folder\",\n\
\ destinationId: 8460057768683396\n};\n\n// Set options\nvar options =\
\ {\n sightId: 5077532685952900,\n body: body\n};\n\n// Move Dashboard\n\
smartsheet.sights.moveSight(options)\n .then(function(movedSight) {\n \
\ console.log(movedSight);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sights.move_sight(\n 5363568917931908,\
\ # sight_id\n smartsheet.models.ContainerDestination({\n\
\ 'destination_type': 'folder', # folder, workspace, or home\n\
\ 'destination_id': 8460057768683396 # destination folder_id\n \
\ })\n)\n"
- lang: Ruby
source: "# Specify destination\nbody = {\n destination_type: 'folder',\n\
\ destination_id: 8460057768683396\n}\n\n# Move Dashboard\nresponse = smartsheet.sights.move(\n\
\ sight_id: 5363568917931908,\n body: body\n)\nmoved_sight = response[:result]\n"
/sights/{sightId}/publish:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1sights~1%7BsightId%7D/parameters/1'
get:
summary: Get Dashboard Publish Status
description: Gets the dashboard 'publish' settings.
operationId: get-sight-publish-status
tags:
- sights
security:
- APIToken: []
- OAuth2:
- READ_SIGHTS
responses:
'200':
description: SightPublish object
content:
application/json:
schema:
description: Describes the dashboard's publish settings.
type: object
properties:
readOnlyFullAccessibleBy:
description: >
Indicates who can access the 'Read-Only Full' view of the
published dashboard. Only returned in the response if
**readOnlyFullEnabled = true**.
* **ALL** - available to anyone who has the link.
* **ORG** - available only to members of the dashboard owner's
Smartsheet organization account.
* **SHARED** - available only to users shared to the item.
---
If **readOnlyFullEnabled** is set to true in the request, but
**readOnlyFullAccessibleBy** is not specified, the value of
**readOnlyFullAccessibleBy** defaults to the organization-level
'Dashboard Publishing' setting (if the dashboard owner belongs
to an organization account) or to **ALL** (if the dashboard
owner does not belong to an organization account).
type: string
enum:
- ALL
- ORG
readOnlyFullEnabled:
description: If true, a rich version of the dashboard is published
with the ability to use shortcuts and widget interactions.
type: boolean
readOnlyFullUrl:
description: URL for 'Read-Only Full' view of the published dashboard.
Only returned in a response if readOnlyFullEnabled = true.
type: string
readOnly: true
required:
- readOnlyFullEnabled
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}/publish \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "SightPublish publish = smartsheet.SightResources.GetPublishStatus(\n\
\ 5363568917931908 // sightId\n );\n"
- lang: Java
source: "SightPublish publish = smartsheet.sightResources().getPublishStatus(\n\
\ 5363568917931908L // long sightId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sightId: 5363568917931908\n};\n\
\n// Get dashboard publish status\nsmartsheet.sights.getSightPublishStatus(options)\n\
\ .then(function(status) {\n console.log(status);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "status = smartsheet_client.Sights.get_publish_status(\n 5363568917931908)\
\ # sight_id\n"
- lang: Ruby
source: "status = smartsheet.sights.get_publish_status(\n sight_id: 5363568917931908\n\
)\n"
put:
summary: Set Dashboard Publish Status
description: Publishes or unpublishes a dashboard.
operationId: set-sight-publish-status
tags:
- dashboards
security:
- APIToken: []
- OAuth2:
- ADMIN_SIGHTS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1sights~1%7BsightId%7D~1publish/get/responses/200/content/application~1json/schema'
responses:
'200':
description: SightPublish object
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1publish/put/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1sights~1%7BsightId%7D~1publish/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sights~1%7BsightId%7D~1publish/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}/publish \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n-H \"Content-Type:\
\ application/json\"\n-X PUT\n-d '{\n \"readOnlyFullEnabled\": true,\n\
\ \"readOnlyFullAccessibleBy\": \"ALL\"\n}' \\\n"
- lang: C#
source: "SightPublish publish = new SightPublish();\npublish.ReadOnlyFullEnabled\
\ = true;\nsmartsheet.SightResources.SetPublishStatus(\n 5363568917931908,\
\ // sightId\n publish\n);\n"
- lang: Java
source: "SightPublish publish = new SightPublish();\npublish.setReadOnlyFullEnabled(true);\n\
smartsheet.sightResources().setPublishStatus(\n 5363568917931908L,\
\ // long sightId\n publish\n );\n"
- lang: JavaScript
source: "// Specify property to change\nvar body = {\n readOnlyFullEnabled:\
\ false\n};\n\n// Set options\nvar options = {\n sightId: 5363568917931908,\n\
\ body: body\n};\n\n// Set dashboard publish status\nsmartsheet.sights.setSightPublishStatus(options)\n\
\ .then(function(newStatus) {\n console.log(newStatus);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sights.set_publish_status(\n 5363568917931908,\
\ # sight_id\n smartsheet.models.SightPublish({\n 'read_only_full_enabled':\
\ True\n })\n)\n"
- lang: Ruby
source: "# Set options\nbody = {\n read_only_full_enabled: true,\n read_only_full_accessible_by:\
\ 'ALL'\n}\n\n# Set dashboard publish status\nresponse = smartsheet.sights.set_publish_status(\n\
\ sight_id: 5363568917931908,\n body: body\n)\nstatus = response[:result]\n"
/sights/{sightId}/shares:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1sights~1%7BsightId%7D/parameters/1'
post:
summary: Share Dashboard
description: Shares a dashboard with the specified users and groups.
operationId: share-sight
tags:
- dashboards
- sharing
security:
- APIToken: []
- OAuth2:
- SHARE_SIGHTS
parameters:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/parameters/0'
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: >
Result object containing either a single Share object or an array of
Share objects, corresponding to what was
specified in the request. All shares have scope=ITEM.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1sights~1%7BsightId%7D~1shares/post/requestBody/content/application~1json/schema'
- type: array
items:
$ref: '#/paths/~1sights~1%7BsightId%7D~1shares/post/requestBody/content/application~1json/schema'
'400':
description: >
If called with a single Share object, and that user or group share
already exists, error code 1025 is returned.
If called with an array of Share objects, and one or more user or group
shares in the array already exist,
they are ignored and omitted from the response.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sights~1%7BsightId%7D~1shares/post/responses/400/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/sights/{sightId}/shares?sendEmail=true'\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n-H \"Content-Type:\
\ application/json\"\n-X POST\n-d '[{\"email\": \"jane.doe@smartsheet.com\"\
, \"accessLevel\": \"VIEWER\"}]'\n"
- lang: C#
source: "Share share = new Share {\n Type = ShareType.USER,\n AccessLevel\
\ = AccessLevel.EDITOR,\n Email = \"jane.doe@smartsheet.com\"\n}\nList\
\ sightShares = smartsheet.SightResources.ShareResources.ShareTo(\n 6327127650920324,\
\ // sightId\n new Share[] { share }, // IEnumerable\
\ shares\n true // bool sendEmail\n);\n"
- lang: Java
source: "// Specify share (to one user as Viewer)\nShare shareSpecification\
\ = new Share()\n .setEmail(\"jane.doe@smartsheet.com\")\n \
\ .setAccessLevel(AccessLevel.VIEWER);\n\n// Share dashboard\nList\
\ addressList = smartsheet.sightResources().shareResources().shareTo(\n\
\ 4583614634583940L, // long sightId\n \
\ (Arrays.asList(shareSpecification)),\n true \
\ // Boolean sendEmail\n );\n"
- lang: JavaScript
source: "// Specify share (to one user as Viewer)\nvar share = [\n {\n \
\ \"email\": \"jane.doe@smartsheet.com\",\n \"accessLevel\": \"VIEWER\"\
\n }\n];\n\n// Set options\nvar options = {\n sightId: 6327127650920324,\n\
\ body: share\n};\n\n// Share dashboard\nsmartsheet.sights.share(options)\n\
\ .then(function(addressList) {\n console.log(addressList);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sights.share_sight(\n 6327127650920324,\
\ # sight_id\n smartsheet.models.Share({\n 'access_level': 'VIEWER',\n\
\ 'email': 'jane.doe@smartsheet.com'\n }),\n True \
\ # sendEmail\n)\n"
- lang: Ruby
source: "body = {\n email: 'jane.doe@smartsheet.com',\n access_level: 'VIEWER',\n\
\ subject: 'This dashboard has been shared with you!',\n message: 'This\
\ Smartsheet dashboard is ready for your inspection.'\n}\n\nresponse = smartsheet.sights.share.create(\n\
\ sight_id: 6327127650920324,\n body: body\n)\n"
get:
summary: List Dashboard Shares
description: Gets a list of all users and groups to whom the specified dashboard
is shared, and their access level.
operationId: list-sight-shares
tags:
- dashboards
- sharing
security:
- APIToken: []
- OAuth2:
- READ_SIGHTS
parameters:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: >
IndexResult object containing an array of Share objects. By default,
this operation returns only item-level
shares (scope=ITEM). Use the sharingInclude parameter to request that
workspace-level shares (scope=WORKSPACE)
also be returned.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/paths/~1sights~1%7BsightId%7D~1shares/post/requestBody/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sights~1%7BsightId%7D~1shares/post/responses/400/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}/shares\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "PaginatedResult shares = smartsheet.SightResources.ShareResources.ListShares(\n\
\ 6327127650920324, // sightId\n null, // Pagination\
\ parameters\n ShareScope.Item // ShareScope shareScope\n);\n"
- lang: Java
source: "//Sample 1: List all\nsmartsheet.sightResources().shareResources().listShares(\n\
\ 6327127650920324L, // long sightId\n null, // PaginationParameters\n\
\ true // includeWorkspaceShares\n );\n\n//Sample 2: Paginate\
\ the list\nPaginationParameters paginationParameters = new PaginationParameters(\n\
\ false, // includeAll\n 100, // pageSize\n 1 \
\ // page\n );\nsmartsheet.sightResources().shareResources().listShares(\n\
\ 6327127650920324L, // long sightId\n paginationParameters,\n\
\ true // includeWorkspaceShares\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sightId: 6327127650920324\n}\n\
\n// List dashboard shares\nsmartsheet.sights.listShares(options)\n .then(function(shareList)\
\ {\n console.log(shareList);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Sights.list_shares(\n\
\ 6327127650920324, # sight_id\n include_all=True)\nshares = response.data\n\
\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Sights.list_shares(\n\
\ 6327127650920324, # sight_id\n page_size=10,\n page=1)\npages\
\ = response.total_pages\nshares = response.data\n"
- lang: Ruby
source: "response = smartsheet.sights.share.list(\n sight_id: 6327127650920324\n\
)\nshares = response[:data]\n"
/sights/{sightId}/shares/{shareId}:
parameters:
- $ref: '#/paths/~1sights~1%7BsightId%7D/parameters/1'
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares~1%7BshareId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Dashboard Share
description: Gets a list of all users and groups to whom the specified dashboard
is shared, and their access level.
operationId: share-sight-get
tags:
- dashboards
- sharing
security:
- APIToken: []
- OAuth2:
- READ_SIGHTS
responses:
'200':
description: Returns Share object.
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}/shares/{shareId}\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Share share = smartsheet.SightResources.ShareResources.GetShare(\n\
\ 6327127650920324, // long sightId\n \"AAABbMomFOeE\" \
\ // string shareId\n);\n"
- lang: Java
source: "Share share = smartsheet.sightResources().shareResources().getShare(\n\
\ 6327127650920324L, // long sightId\n \"AAABbMomFOeE\"\
\ // string shareId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sightId: 6327127650920324,\n \
\ shareId: \"AAABbMomFOeE\"\n}\n\n// Get dashboard share\nsmartsheet.sights.getShare(options)\n\
\ .then(function(share) {\n console.log(share);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "share = smartsheet_client.Sights.get_share(\n 6327127650920324,\
\ # sight_id\n 'AAACOqOmFOeE') # share_id\n"
- lang: Ruby
source: "share = smartsheet.sights.share.get(\n sight_id: 6327127650920324,\n\
\ share_id: 'AAABbMomFOeE'\n)\n"
delete:
summary: Delete Dashboard Share
description: Deletes the share specified in the URL.
operationId: delete-sight-share
tags:
- dashboards
- sharing
security:
- APIToken: []
- OAuth2:
- SHARE_SIGHTS
responses:
'200':
description: Returns Result object.
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sights~1%7BsightId%7D~1shares~1%7BshareId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.SightResources.ShareResources.DeleteShare(\n 6327127650920324,\
\ // sightId\n \"AAABbMomFOeE\" // string shareId\n);\n"
- lang: Java
source: "smartsheet.sightResources().shareResources().deleteShare(\n \
\ 6327127650920324L, // long sightId\n \"AAABbMomFOeE\"\
\ // string shareId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n sightId: 6327127650920324,\n \
\ shareId: \"AAABbMomFOeE\"\n}\n\n// Delete dashboard share\nsmartsheet.sights.deleteShare(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Sights.delete_share(\n 6327127650920324, \
\ # sight_id\n 'AAACOqOmFOeE') # share_id\n"
- lang: Ruby
source: "smartsheet.sights.share.delete(\n sight_id: 6327127650920324,\n\
\ share_id: 'AAABbMomFOeE'\n)\n"
put:
summary: Update Dashboard Share
description: Updates the access level of a user or group for the specified dashboard.
operationId: update-sight-share
tags:
- dashboards
- sharing
security:
- APIToken: []
- OAuth2:
- SHARE_SIGHTS
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1sights~1%7BsightId%7D~1shares~1%7BshareId%7D/get/responses/200/content/application~1json/schema'
responses:
'200':
description: Returns Result object containing the modified Share object.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1sights~1%7BsightId%7D~1shares~1%7BshareId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: object
items:
$ref: '#/paths/~1sights~1%7BsightId%7D~1shares~1%7BshareId%7D/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1sights~1%7BsightId%7D~1shares~1%7BshareId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/sights/{sightId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{\"accessLevel\": \"VIEWER\"}'\n"
- lang: C#
source: "Share updatedShare = smartsheet.SightResources.ShareResources.UpdateShare(\n\
\ 6327127650920324, // sightId\n new Share { //\
\ Share share\n Id = \"AAALRqomFOeE\", // string shareId\n AccessLevel\
\ = AccessLevel.VIEWER // AccessLevel accessLevel\n }\n);\n"
- lang: Java
source: "// Set the access level to Viewer\nShare shareSpecification = new\
\ Share();\n shareSpecification.setAccessLevel(AccessLevel.VIEWER)\n\
\ .setId(\"AAAFeF82FOeE\"); // string shareId\n\n// Update dashboard\
\ share\nShare updatedShare = smartsheet.sightResources().shareResources().updateShare(\n\
\ 6327127650920324L, // long sightId\n shareSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Set access level to Viewer\nvar shareSpecification = {\"accessLevel\"\
: \"VIEWER\"};\n\n// Set options\nvar options = {\n sightId: 6327127650920324,\n\
\ shareId: \"AAALRqomFOeE\",\n body: shareSpecification\n};\n\n// Update\
\ dashboard share\nsmartsheet.sights.updateShare(options)\n .then(function(updatedShare)\
\ {\n console.log(updatedShare);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_share = smartsheet_client.Sights.update_share(\n 6327127650920324,\
\ # sight_id\n 'AAALRqomFOeE', # share_id\n smartsheet.models.Share({\n\
\ 'access_level': 'VIEWER'\n })\n)\n"
- lang: Ruby
source: "body = {\n access_level: 'VIEWER'\n}\n\nresponse = smartsheet.sights.share.update(\n\
\ sight_id: 6327127650920324,\n share_id: 'AAABbMomFOeE',\n body: body\n\
)\n"
/templates:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List User-Created Templates
description: Gets a list of user-created templates that the user has access
to.
operationId: templates-list
tags:
- templates
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of Templates
type: array
items:
$ref: '#/components/schemas/Folder/properties/templates/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/templates \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult templates\
\ = smartsheet.TemplateResources.ListUserCreatedTemplates(\n null \
\ // PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult templates =\
\ smartsheet.templateResources().listUserCreatedTemplates(\n null\
\ // PaginationParameters\n );\n"
- lang: JavaScript
source: "smartsheet.templates.listUserCreatedTemplates()\n .then(function(templateList)\
\ {\n console.log(templateList);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Templates.list_user_created_templates(\n\
\ page_size=10,\n page=1)\npages = response.total_pages\ntemplates = response.data\n"
- lang: Ruby
source: "response = smartsheet.templates.list\ntemplates = response[:data]\n"
/templates/public:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Public Templates
description: Gets a list of public templates that the user has access to.
operationId: templates-listPublic
tags:
- templates
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- name: level
in: query
required: false
description: Level of public template types. 0 refers to only Sheet types,
1 refers to all types.
schema:
type: number
enum:
- 0
- 1
default: 0
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of Templates
type: array
items:
$ref: '#/components/schemas/Folder/properties/templates/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/templates/public \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult templates\
\ = smartsheet.TemplateResources.ListPublicTemplates(\n null \
\ // PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult templates =\
\ smartsheet.templateResources().listPublicTemplates(\n null \
\ // PaginationParameters\n );\n"
- lang: JavaScript
source: "smartsheet.templates.listPublicTemplates()\n .then(function(templateList)\
\ {\n console.log(templateList);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Templates.list_public_templates(\n \
\ page_size=10,\n page=1)\npages = response.total_pages\ntemplates = response.data\n"
- lang: Ruby
source: "response = smartsheet.templates.list_public\ntemplates = response[:data]\n"
/token:
post:
summary: Gets or Refreshes an Access Token
description: Gets or refreshes an access token, as part of the OAuth process.
operationId: tokens-getOrRefresh
tags:
- token
parameters:
- name: Content-Type
in: header
description: >
Required for POST and PUT requests. Defines the structure for the
response.
schema:
type: string
enum:
- application/x-www-form-urlencoded
- in: query
name: client_id
schema:
type: string
description: The client Id you obtained when you registered your app.
required: true
- in: query
name: client_secret
schema:
type: string
description: (Optional) Must use either this value or hash. Plain text method
for sending this value. For example, client_secret={app_secret}. Encryption
occurs at the HTTPS level.
- in: query
name: code
schema:
type: string
description: Authorization code acquired after user selects "Allow" in the
Web login UI.
- in: query
name: grant_type
schema:
type: string
enum:
- authorization_code
- refresh_token
required: true
description: Must be set to "authorization_code".
- in: query
name: hash
schema:
type: string
description: (Optional) Must use either this value or client_secret. SHA-256
hash of your app secret concatenated with a pipe and the authorization code.
For example, hash={SHA_256(app_secret|code)}.
- in: query
name: refresh_token
schema:
type: string
description: refresh_token value that came with the access token.
- in: query
name: redirect_url
schema:
type: string
description: Deprecated. If supplied, must match the redirect URI you registered
for your app.
responses:
'200':
description: An access token
content:
application/json:
schema:
type: object
properties:
access_token:
description: A credential that can be used by a client to access
the Smartsheet API.
type: string
readOnly: true
token_type:
description: How an access token will be generated and presented.
Smartsheet uses the bearer parameter, which means essentially
give access to the bearer of this token.
type: string
readOnly: true
expires_in:
description: Number of seconds token is valid once issued.
type: number
default: 604799
readOnly: true
refresh_token:
description: A credential tied to the access token that can be
used to obtain a fresh access token with the same permissions,
without further involvement from a user.
type: string
readOnly: true
default:
description: Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "// Sample 1: Get access token\n// Option 1: Use a hash\ncurl https://api.smartsheet.com/2.0/token\
\ \\\n-d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&hash={SHA_256(app_secret|code)}'\
\ \\\n-X POST\n\n// Option 2: Use plain text\ncurl https://api.smartsheet.com/2.0/token\
\ \\\n-d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&client_secret={app_secret}'\
\ \\\n-X POST\n\n// Sample 2: Refresh access token\n// Option 1: Use a hash\n\
curl https://api.smartsheet.com/2.0/token \\\n-d 'grant_type=refresh_token&refresh_token={your_refresh_token}&client_id={your_client_id}&hash={SHA_256(app_secret|refresh_token)}'\
\ \\\n-X POST\n\n// Option 2: Use plain text\ncurl https://api.smartsheet.com/2.0/token\
\ \\\n-d 'grant_type=refresh_token&refresh_token={your_refresh_token}&client_id={your_client_id}&client_secret={app_secret}'\
\ \\\n-X POST\n\n"
- lang: C#
source: "// Sample 1: Get access token\n// Option 1: Use a hash\nToken token\
\ = oauth.ObtainNewToken(\n authResult // AuthorizationResult authResult\n\
);\n\n// Option 2: Use plain text\n// In progress\n\n// Sample 2: Refresh\
\ access token\nToken tokenRefreshed = oauth.RefreshToken(token);\n\n"
- lang: JavaScript
source: "// Sample 1: Get access token\n// Option 1: Use a hash\n// Create\
\ hash\nvar hash =\n crypto.createHash('sha256')\n .update('9samp7le3for71you'\
\ + '|' + 'sample6p9qisx6a')\n // ('Your App Secret' + '|' + 'Received\
\ Authorization Code')\n .digest('hex');\n\n// Set options\nvar options\
\ = {\n queryParameters: {\n client_id: '1samp48lel5for68you', //\
\ Your App Client ID\n code: 'sample6p9qisx6a', // Received\
\ Authorization Code\n hash: hash\n },\n contentType: 'application/x-www-form-urlencoded'\n\
};\n\n// Get access token\nsmartsheet.tokens.getAccessToken(options)\n \
\ .then(function(token) {\n console.log(token);\n})\n.catch(function(error)\
\ {\n console.log(error);\n });\n\n// Option 2: Use plain text\n// In\
\ progress\n\n// Sample 2: Refresh access token\n// Create hash\nvar hash\
\ =\n crypto.createHash('sha256')\n .update('9samp7le3for71you' + '|'\
\ + 'sample6p9qisx6a')\n // ('Your App Secret' + '|' + 'Your App\
\ Refresh Token')\n .digest('hex');\n\n// Set options\nvar options =\
\ {\n queryParameters: {\n client_id: '1samp48lel5for68you', // Your\
\ App Client ID\n refresh_token: 'e9x352a9mp4151le2505',\n hash: hash\n\
\ },\n contentType: 'application/x-www-form-urlencoded'\n};\n\n// Refresh\
\ access token\nsmartsheet.tokens.refreshAccessToken(options)\n .then(function(updatedToken)\
\ {\n console.log(updatedToken);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Ruby
source: "# Sample 1: Get access token\n# Option 1: Use a hash\nhash = Digest::SHA256.hexdigest\
\ '9samp7le3for71you|sample6p9qisx6a'\n #\
\ your_app_secret|your_code\nsmartsheet.token.get(\n client_id: '1samp48lel5for68you',\n\
\ code: 'sample6p9qisx6a',\n hash: hash\n)\n\n# Option 2: Use plain text\n\
# In progress\n\n# Sample 2: Refresh access token\nhash = Digest::SHA256.hexdigest\
\ '9samp7le3for71you|e9x352a9mp4151le2505'\n \
\ # 'your_app_secret|refresh_token\nsmartsheet.token.refresh(\n client_id:\
\ '1samp48lel5for68you',\n refresh_token: 'e9x352a9mp4151le2505',\n hash:\
\ hash\n)\n\n"
delete:
summary: Revoke Access Token
description: Revokes the access token used to make this request. The access
token is no longer valid, and subsequent API calls made using the token fail.
operationId: tokens-delete
tags:
- token
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: deleteAllForApiClient
in: query
schema:
type: boolean
default: false
description: The client Id and user Id is fetched based on the token that
is used to make this API call. A value of true deletes all tokens associated
to the given client Id and user Id.
required: false
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
default:
description: Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1token/post/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/token \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.TokenResources.RevokeAccessToken();\n"
- lang: Java
source: "smartsheet.tokenResources().revokeAccessToken();\n"
- lang: JavaScript
source: "smartsheet.tokens.revokeAccessToken({})\n .then(function(results)\
\ {\n console.log(results);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Token.revoke_access_token()\n"
- lang: Ruby
source: "smartsheet.token.revoke\n"
/users:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
operationId: list-users
summary: List Users
description: >
Gets a list of users in the organization account. To filter by email,
use the optional email query string parameter to specify a list of
users' email addresses.
**NOTE:** If the API request is submitted by a system administrator, the following
User object attributes are included in the response (else, they are omitted
from the response):
* **admin**
* **groupAdmin**
* **licensedSheetCreator**
* **resourceViewer**
* **sheetCount (omitted if the status attribute is not ACTIVE)**
* **status**
**NOTE:** If the API request is submitted by a system administrator of an
Enterprise account, and [Custom Welcome Screen](https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only)
is enabled, the following [User object](../../tag/usersObjects#section/User-Object)
attributes are included in the response (else, they are omitted from the response):
* **customWelcomeScreenViewed** (omitted if the user has never viewed the
[Custom Welcome Screen](https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only))
tags:
- users
security:
- APIToken: []
- OAuth2:
- READ_USERS
parameters:
- name: email
description: Comma-separated list of email addresses on which to filter the
results.
in: query
required: false
schema:
type: string
- name: include
description: >
If the API request is submitted by a system administrator and when
specified with a value of 'lastLogin', response includes a lastLogin
attribute for each user that indicates the Last login date/time of
the user.
**Note** If the number of users included in the response is > 100, you must
paginate your query to see the lastLogin attribute. For large responses,
the lastLogin attribute is never included.
in: query
required: false
schema:
type: string
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/1'
- $ref: '#/paths/~1contacts/get/parameters/2'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: >
IndexResult object containing an array of [User
objects](../../tag/usersObjects#section/User-Object)
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: List of User Objects
type: array
items:
description: User Object
type: object
properties:
id:
description: User Id.
type: number
readOnly: true
example: 48569348493401200
admin:
description: Indicates whether the user is a system admin
(can manage user accounts and organization account).
type: boolean
default: false
example: true
customWelcomeScreenViewed:
description: Timestamp of viewing an [Enterprise Custom
Welcome Screen](https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only)
by the current user.
type: string
format: date-time
readOnly: true
example: 2020-08-25T12:15:47Z
email:
description: User's primary email address.
type: string
format: email
example: jane.doe@smartsheet.com
firstName:
description: User's first name.
type: string
example: Jane
groupAdmin:
description: Indicates whether the user is a group admin
(can create and edit groups).
type: boolean
default: false
example: true
lastLogin:
description: Last login time of the current user.
type: string
format: date-time
readOnly: true
example: 2020-10-04T18:32:47Z
lastName:
description: User's last name.
type: string
example: Doe
licensedSheetCreator:
description: Indicates whether the user is a licensed
user (can create and own sheets).
type: boolean
default: false
example: true
name:
description: User's full name (read-only).
type: string
readOnly: true
example: Jane Doe
profileImage:
$ref: '#/components/schemas/User/properties/profileImage'
resourceViewer:
description: Indicates whether the user is a resource
viewer (can access resource views).
type: boolean
default: false
example: true
sheetCount:
description: The number of sheets owned by the current
user within the organization account.
type: number
readOnly: true
example: 42
status:
description: User status, set to one of the listed enum
values.
type: string
enum:
- ACTIVE
- DECLINED
- PENDING
example: ACTIVE
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/users?email=john.doe@smartsheet.com&include=lastLogin'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Sample 1: Omit 'email' parameter and pagination parameters\nPaginatedResult\
\ users = smartsheet.UserResources.ListUsers(\n null, //\
\ IEnumerable emails\n null // PaginationParameters\n\
);\n\n// Sample 2: Specify 'email' parameter with value of \"john.doe@smartsheet.com\"\
\ and 'includeAll' parameter with value of 'true'\nPaginatedResult\
\ users = smartsheet.UserResources.ListUsers(\n new string[] { \"john.doe@smartsheet.com\"\
\ },\n new PaginationParameters(\n true, // includeAll\n null, //\
\ int pageSize\n null) // int page\n);\n"
- lang: Java
source: "// Sample 1: Omit 'email' parameter and pagination parameters\nPagedResult\
\ users = smartsheet.userResources().listUsers(\n null, //\
\ Set email\n null // PaginationParameters\n \
\ );\n\n// Sample 2: Specify pagination parameter 'includeAll'\nPaginationParameters\
\ parameters = new PaginationParameters()\n .setIncludeAll(true);\n\
\n// Specify 'email' parameter with value of \"john.doe@smartsheet.com\"\
\ and 'includeAll' parameter with value of 'true'\nPagedResult users\
\ = smartsheet.userResources().listUsers( new HashSet(Arrays.asList(\"john.doe@smartsheet.com\"\
)), parameters);\n"
- lang: JavaScript
source: "smartsheet.users.listAllUsers()\n\t.then(function(userList) {\n\t\
\tconsole.log(userList)\n\t})\n\t.catch(function(error) {\n\t\tconsole.log(error);\n\
\t});\n"
label: Node.js
- lang: Python
source: "# Sample 1; List all\nresponse = smartsheet_client.Users.list_users(include_all=True)\n\
users = response.data\n\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Users.list_users(\n\
\ page_size=100,\n page=1)\npages = response.total_pages\nusers = response.data\n"
- lang: Ruby
source: "response = smartsheet.users.list\nusers = response[:data]\n"
post:
operationId: add-user
summary: Add User
description: >
Adds a user to the organization account.
* **_This operation is only available to system administrators_**
* **If successful, and user auto provisioning (UAP) is on, and user matches
the auto provisioning rules, user is added to the org. If UAP is off, or user
does not match UAP rules, user is invited to the org and must explicitly accept
the invitation to join.**
* **In some specific scenarios, supplied attributes such as firstName and
lastName may be ignored. For example, if you are inviting an existing Smartsheet
user to join your organization account, and the invited user has not yet accepted
your invitation, any supplied firstName and lastName are ignored.**
tags:
- users
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
parameters:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/parameters/0'
requestBody:
description: The User to be created
content:
application/json:
schema:
$ref: '#/paths/~1users/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
responses:
'200':
description: >
Result object containing the newly created [User
object](../../tag/usersObjects#section/User-Object).
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1users/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: >
If an error occurs because the request specified the alternate email
address (that is, not the primary email address) of an existing
Smartsheet user (to invite the user into the org), the Error object
returned contains a detail attribute set to an array of objects,
each object in the array having the following attributes:
* alternateEmailAddress: User's alternate email address that was specified
in the request
* primaryEmailAddress: User's primary email address that must instead
be specified for the operation
For example:
```
{
"errorCode": 5xxx,
"message": "The specified email address (u1+1@smartsheet.com) is an
alternate address for a user with the primary email address of u1@smartsheet.com.
Please retry using their primary address."
"detail": [
{
"alternateEmailAddress": "u1+1@smartsheet.com",
"primaryEmailAddress": "u1@smartsheet.com"
}
]
}
```
content:
application/json:
schema:
$ref: '#/paths/~1users/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/users?sendEmail=true' \\\n-H\
\ \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"firstName\": \"John\", \"lastName\"\
: \"Doe\", \"email\": \"john.doe@smartsheet.com\", \"admin\": false, \"\
licensedSheetCreator\": true}'\n"
- lang: C#
source: "// Set user properties\nUser userSpecification = new User\n{\n Email\
\ = \"john.doe@smartsheet.com\",\n Admin = false,\n LicensedSheetCreator\
\ = true,\n FirstName = \"John\",\n LastName = \"Doe\"\n};\n\n// Add user\n\
User newUser = smartsheet.UserResources.AddUser(\n userSpecification,\n\
\ true, // Nullable sendEmail\n null \
\ // Nullable allowInviteAccountAdmin\n);\n"
- lang: Java
source: "// Set user properties\nUser userSpecification = new User();\nuserSpecification.setAdmin(false)\n\
\ .setEmail(\"john.doe@smartsheet.com\")\n .setFirstName(\"\
John\")\n .setLastName(\"Doe\")\n .setLicensedSheetCreator(true);\n\
\n// Add user\nUser newUser = smartsheet.userResources().addUser(userSpecification);\n"
- lang: JavaScript
source: "// Specify user properties\nvar user = {\n\t\"firstName\": \"John\"\
,\n\t\"lastName\": \"Doe\",\n\t\"email\": \"john.doe@smartsheet.com\",\n\
\t\"admin\": false,\n\t\"licensedSheetCreator\": true\n};\n\n// Set options\n\
var options = {\n\tbody: user\n};\n\n// Add user\nsmartsheet.users.addUser(options)\n\
\t.then(function(newUser) {\n\t\tconsole.log(newUser)\n\t}).catch(function(error)\
\ {\n\t\tconsole.log(error);\n\t});\n"
label: Node.js
- lang: Python
source: "new_user = smartsheet_client.Users.add_user(\n smartsheet.models.User({\n\
\ 'first_name': 'John',\n 'last_name': 'Doe',\n 'email': 'john.doe@smartsheet.com',\n\
\ 'admin': False,\n 'licensed_sheet_creator': True\n })\n)\n"
- lang: Ruby
source: "# Set user properties\nbody = {\n email: 'john.doe@smartsheet.com',\n\
\ admin: false,\n licensed_sheet_creator: false,\n first_name: 'John',\n\
\ last_name: 'Doe',\n resource_viewer: false\n}\n\n# Add user\nresponse\
\ = smartsheet.users.add(\n body: body\n)\nnew_user = response[:result]\n"
/users/me:
get:
operationId: get-current-user
summary: Get Current User
description: >
Gets the current user
**NOTE:** For system administrators, the following UserProfile attributes
are included in the response:
* **customWelcomeScreenViewed** (only returned when an Enterprise user has
viewed the [Custom Welcome Screen](https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only))
* **lastLogin** (only returned if the user has logged in)
* **sheetCount** (only returned if the status attribute is ACTIVE)
tags:
- users
security:
- APIToken: []
- OAuth2: []
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: include
description: When specified with a value of 'groups', response includes an
array of groups (groupId, name, and description only) that the user is a
member of.
in: query
required: false
schema:
type: string
enum:
- groups
responses:
'200':
description: |
IndexResult object containing a UserProfile object.
content:
application/json:
schema:
allOf:
- type: object
properties:
id:
description: Current user's Id.
type: number
example: 48569348493401200
account:
$ref: '#/components/schemas/UserProfile/properties/account'
admin:
description: Indicates whether the user is a system admin (can
manage user accounts and organization account).
type: boolean
example: true
alternateEmails:
$ref: '#/components/schemas/UserProfile/properties/alternateEmails'
company:
description: User's company.
type: string
example: Smartsheet
customWelcomeScreenViewed:
description: Timestamp of viewing an [Enterprise Custom Welcome
Screen](https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only)
by the current user.
type: string
format: date-time
example: 2020-08-25T12:15:47Z
department:
description: User's department.
type: string
example: Engineering
email:
description: Current user's primary email address.
type: string
example: john.doe@smartsheet.com
firstName:
description: Current user's first name.
type: string
example: John
groupAdmin:
description: Indicates whether the user is a group admin (can
create and edit groups).
type: boolean
example: true
jiraAdmin:
description: Indicates whether the user is a JIRA admin.
type: boolean
example: true
lastLogin:
description: Last login time of the current user.
type: string
format: date-time
example: 2020-10-31T12:15:47Z
lastName:
description: Current user's last name.
type: string
example: Doe
licensedSheetCreator:
description: Indicates whether the user is a licensed user (can
create and own sheets).
type: boolean
example: true
locale:
description: Current user's locale (see [Server Information](../../tag/serverInfoObjects#section/Server-Info-Object)).
type: string
example: en_US
mobilePhone:
description: User's mobile phone number.
type: string
example: 555-867-5309
profileImage:
$ref: '#/components/schemas/User/properties/profileImage'
resourceViewer:
description: Indicates whether the user is a resource viewer
(can access resource views).
type: boolean
example: true
role:
description: User's role.
type: string
example: Software Developer
salesforceAdmin:
description: Indicates whether the user is a Salesforce admin.
type: boolean
example: false
salesforceUser:
description: Indicates whether the user is a registered Salesforce
user.
type: boolean
example: false
sheetCount:
description: The number of sheets owned by the current user
within the organization account.
type: number
example: 42
timeZone:
description: Current user's time zone Id.
type: string
example: US/Pacific
title:
description: User's title.
type: string
example: Senior Software Engineer
workPhone:
description: User's work phone number.
type: string
example: 844-324-2360
- type: object
properties:
data:
description: List of Groups
type: array
items:
$ref: '#/paths/~1groups/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/me \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "UserProfile userProfile = smartsheet.UserResources.GetCurrentUser();\n"
- lang: Java
source: "UserProfile userProfile = smartsheet.userResources().getCurrentUser();\n"
- lang: JavaScript
source: "smartsheet.users.getCurrentUser()\n .then(function(userProfile)\
\ {\n console.log(userProfile);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "user_profile = smartsheet_client.Users.get_current_user()\n"
- lang: Ruby
source: "user_profile = smartsheet.users.get_current\n"
/users/sheets:
get:
operationId: list-org-sheets
summary: List Org Sheets
description: >
Gets a summarized list of all sheets owned by the members of the
organization account.
* **_This operation is only available to system administrators_**
* **_You may use the query string parameter numericDates with a value of true
to enable strict parsing of dates in numeric format. See Dates and Times for
more information._**
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/1'
responses:
'200':
description: >
IndexResult object containing an array of Sheet objects, limited to
the following attributes:
* id
* name
* owner (email address)
* ownerId
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: List of Sheets
type: array
items:
type: object
properties:
id:
description: Sheet Id.
type: number
name:
description: Sheet name.
type: string
owner:
description: Email address of the sheet owner.
type: string
ownerId:
description: User Id of the sheet owner.
type: number
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/sheets \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "PaginatedResult sheets = smartsheet.UserResources.SheetResources.ListOrgSheets(\n\
\ null, // PaginationParameters\n null //\
\ Nullable modifiedSince\n);\n"
- lang: Java
source: "PagedResult sheets = smartsheet.userResources().listOrgSheets();\n"
- lang: JavaScript
source: "smartsheet.sheets.listOrganizationSheets()\n .then(function(sheetsList)\
\ {\n console.log(sheetsList)\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Sheets.list_org_sheets()\nsheets = response.data\n"
- lang: Ruby
source: "response = smartsheet.sheets.list_for_org\nsheets = response[:data]\n"
/users/{userId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1groups~1%7BgroupId%7D~1members~1%7BuserId%7D/parameters/2'
get:
operationId: get-user
summary: Get User
description: >
Gets the user specified in the URL.
* NOTE: For system administrators, the following UserProfile attributes are
included in the response):
* **admin**
* **customWelcomeScreenViewed** (only returned when an Enterprise user has
viewed the [Custom Welcome Screen](https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only))
* **groupAdmin**
* **lastLogin** (only returned if the user has logged in)
* **licensedSheetCreator**
* **resourceViewer**
* **sheetCount** (only returned if the status attribute is ACTIVE)
* **status**
tags:
- users
security:
- APIToken: []
- OAuth2:
- READ_USERS
responses:
'200':
description: |
Returns UserProfile object
content:
application/json:
schema:
$ref: '#/paths/~1users~1me/get/responses/200/content/application~1json/schema/allOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/{userId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "UserProfile userProfile = smartsheet.UserResources.GetUser(\n 48569348493401200\
\ // long userId\n);\n"
- lang: Java
source: "UserProfile userProfile = smartsheet.userResources().getUser(\n \
\ 48569348493401200L // long userId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n\tid: 48569348493401200\t// Id of\
\ user\n};\n\n// Get user\nsmartsheet.users.getUser(options)\n .then(function(userProfile)\
\ {\n console.log(userProfile)\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "user_profile = smartsheet_client.Users.get_user(\n 48569348493401200)\
\ # user_id\n"
- lang: Ruby
source: "user_profile = smartsheet.users.get(\n user_id: 48569348493401200\n\
)\n"
delete:
operationId: remove-user
summary: Remove User
description: >
Removes a user from an organization account. User is transitioned to a
free collaborator with read-only access to owned reports, sheets,
Sights, workspaces, and any shared templates (unless those are
optionally transferred to another user).
* **_This operation is only available to system administrators_**
* If the **transferTo** parameter is specified and the removed user owns groups,
the user specified via the **transferTo** parameter must have group admin
rights.
* The **transferTo** and **transferSheets** parameters cannot be specified
for a user who has not yet accepted an invitation to join the organization
account (that is, if user **status=PENDING**).
tags:
- users
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
requestBody:
content:
application/json:
schema:
description: >
Removes a user from an organization account. User is
transitioned to a free collaborator with read-only access to
owned reports, sheets, Sights, workspaces, and any shared
templates (unless those are optionally transferred to another
user).
type: object
properties:
removeFromSharing:
description: >
* Set to **true** to remove the user from sharing for all
sheets/workspaces in the organization account. If not
specified, user is not removed from sharing.
type: boolean
example: true
transferSheets:
description: >
* If **true**, and **transferTo** is specified, the removed
user's sheets are transferred. Else, sheets are not
transferred.
type: boolean
default: false
example: true
transferTo:
description: >
(Required if user owns groups.)
* The Id of the user to transfer ownership to.
* If the user being removed owns groups, they are transferred
to this user. If the user owns sheets, and **transferSheets**
is true, the removed user's sheets are transferred to this user.
type: number
example: 94094820842
responses:
'200':
description: |
Returns Result object
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1users~1%7BuserId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/users/{userId}?transferTo=USER_Id&removeFromSharing=true'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "// Transfer ownership of groups and sheets to another user and remove\
\ the user from sharing\nsmartsheet.UserResources.RemoveUser(\n 94094820842,\
\ // long userId\n transferToUserId, // Nullable\
\ transferTo\n true, // Nullable transferSheets\n\
\ true // Nullable removeFromSharing\n);\n"
- lang: Java
source: "// Transfer ownership of groups and sheets to another user and remove\
\ the user from sharing\nDeleteUserParameters parameters = new DeleteUserParameters(\n\
\ 62123820842L, // long transferToUserId\n true, \
\ // Boolean transferSheets\n true // Boolean\
\ removeFromSharing\n );\n\nsmartsheet.userResources().deleteUser(\n\
\ 94094820842L, // long userId\n parameters\n \
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n\tid: 94094820842 // Id of User\n\
};\n\n// Remove user\nsmartsheet.users.removeUser(options)\n\t.then(function(results)\
\ {\n\t\tconsole.log(results)\n\t})\n\t.catch(function(error) {\n\t\tconsole.log(error);\n\
\t});\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Users.remove_user(\n 94094820842, \
\ # user_id\n transfer_to=62123820842, # ownership of groups and\
\ sheets transfer to user_id\n remove_from_sharing=True)\n"
- lang: Ruby
source: "smartsheet.users.remove(\n user_id: 94094820842\n)\n"
put:
operationId: update-user
summary: Update User
description: Updates the user specified in the URL.
tags:
- users
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
requestBody:
description: |
User object containing at least one of the following attributes:
* admin (required)
* licensedSheetCreator (required)
* firstName (optional)
* groupAdmin (optional)
* lastName (optional)
* resourceViewer (optional)
content:
application/json:
schema:
description: |
Updates User for the following attributes:
* **admin** (required).
* **licensedSheetCreator** (required).
* **firstName** (optional).
* **groupAdmin** (optional).
* **lastName** (optional).
* **resourceViewer** (optional).
type: object
properties:
admin:
description: Indicates whether the user is a system admin (can manage
user accounts and organization account).
type: boolean
default: false
example: true
licensedSheetCreator:
description: Indicates whether the user is a licensed user (can
create and own sheets).
type: boolean
default: false
example: true
firstName:
description: User's first name.
type: string
example: Jane
lastName:
description: User's last name.
type: string
example: Doe
groupAdmin:
description: Indicates whether the user is a group admin (can create
and edit groups).
type: boolean
default: false
example: true
resourceViewer:
description: Indicates whether the user is a resource viewer (can
access resource views).
type: boolean
default: false
example: true
responses:
'200':
description: >
Result object containing the [User
object](../../tag/usersObjects#section/User-Object) for the updated
user
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1users~1%7BuserId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
data:
description: Updated User Properties
type: array
items:
description: User profile image response.
properties:
email:
description: User's primary email address.
type: string
format: email
example: jane.doe@smartsheet.com
name:
description: User's full name (read-only).
type: string
readOnly: true
example: Jane Doe
firstName:
description: User's first name.
type: string
example: Jane
lastName:
description: User's last name.
type: string
example: Doe
profileImage:
$ref: '#/components/schemas/User/properties/profileImage'
id:
description: User Id.
type: number
readOnly: true
example: 48569348493401200
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1users~1%7BuserId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/{userId} \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X PUT \\\n-d '{\"admin\": true, \"licensedSheetCreator\": true}'\n"
- lang: C#
source: "// Specify updated user properties\nUser userSpecification = new\
\ User\n{\n Id = 82349925918590, // userId\n Admin = true,\n LicensedSheetCreator\
\ = true\n};\n\n// Update user\nUser updatedUser = smartsheet.UserResources.UpdateUser(\n\
\ userSpecification\n);\n"
- lang: Java
source: "// Specify updated user properties\nUser userSpecification = new\
\ User();\nuserSpecification.setLicensedSheetCreator(true)\n .setAdmin(true)\n\
\ .setId(82349925918590L); // long userId\n\n// Update user\n\
User updatedUser = smartsheet.userResources().updateUser(userSpecification);\n"
- lang: JavaScript
source: "// Specify updated user properties\nvar user = {\n\t\"admin\": true,\n\
\t\"licensedSheetCreator\": true\n};\n\n// Set options\nvar options = {\n\
\ id: 82349925918590, // Id of User\n body: user\n\t};\n\n// Update user\n\
smartsheet.users.updateUser(options)\n\t.then(function(updatedUser) {\n\t\
\tconsole.log(updatedUser)\n\t}).catch(function(error) {\n\t\tconsole.log(error);\n\
\t});\n"
label: Node.js
- lang: Python
source: "updated_user = smartsheet_client.Users.update_user(\n 82349925918590,\
\ # user_id\n smartsheet.models.User({\n 'licensed_sheet_creator':\
\ True,\n 'admin': True\n })\n)\n"
- lang: Ruby
source: "# Specify updated user properties\nbody = {\n admin: false,\n licensed_sheet_creator:\
\ true,\n first_name: 'Johnny',\n last_name: 'Doeford',\n resource_viewer:\
\ true\n}\n\n# Update user\nresponse = smartsheet.users.update(\n user_id:\
\ 48569348493401200,\n body: body\n)\nupdated_user = response[:result]\n"
/users/{userId}/alternateemails:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1groups~1%7BgroupId%7D~1members~1%7BuserId%7D/parameters/2'
get:
operationId: list-alternate-emails
summary: List Alternate Emails
description: Gets a list of the alternate emails for the specified user.
tags:
- alternateEmailAddress
security:
- APIToken: []
- OAuth2:
- READ_USERS
responses:
'200':
description: >
IndexResult object containing an array of [AlternateEmail
object](/section/AlternateEmail-Object)
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of attachments
type: array
items:
$ref: '#/components/schemas/UserProfile/properties/alternateEmails'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit 'email' parameter and pagination parameters\nPaginatedResult\
\ results = smartsheet.UserResources.ListAlternateEmails(\n 123456789012345,\
\ // long userId\n null // PaginationParameters\n\
);\n"
- lang: Java
source: "// Omit 'email' parameter and pagination parameters\nPagedResult\
\ results = smartsheet.userResources().listAlternateEmails(\n 123456789012345L,\
\ // long userId\n null // PaginationParameters\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n userId: 123456789012345\n};\n\n\
// List alternate email addresses\nsmartsheet.users.listAlternateEmails(options)\n\
\ .then(function(emailList) {\n console.log(emailList);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Users.list_alternate_emails(\n 123456789012345)\
\ # user_id\nemails = response.data\n"
- lang: Ruby
source: "response = smartsheet.users.alternate_emails.list(\n user_id: 123456789012345\n\
)\nemails = response[:data]\n"
post:
operationId: add-alternate-email
summary: Add Alternate Emails
description: |
Adds one or more alternate email addresses for the specified user.
**_This operation is only available to system administrators._**
tags:
- alternateEmailAddress
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
properties:
email:
description: User's alternate email address.
type: string
example: johnathan.doe@smartsheet.com
- type: array
items:
$ref: '#/paths/~1users~1%7BuserId%7D~1alternateemails/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: >
Result object containing an array of the newly created
[AlternateEmail objects](/section/AlternateEmail-Object).
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
data:
description: Updated User Properties
type: array
items:
$ref: '#/paths/~1users~1%7BuserId%7D~1alternateemails/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: >
If a single email address is specified in the request and an error
occurs, the response contains an Error object.
If multiple email addresses are specified in the request and an error
occurs, the Error object returned contains a detail attribute set to an
array of objects, each object in the array having the following attributes:
* email: Problematic email address specified in the request
* errorCode: Smartsheet error code
* message: Message that describes the problem with the specified email
address
For example:
```
{
"errorCode": 1160,
"message": "Invalid bulk request. See detail for more information."
"detail": [
{
"email": "altEmail1@smartsheet.com",
"errorCode": 1157,
"message": "This address is already associated with another Smartsheet
account, so it cannot be added as an alternate address for this account."
}
]
}
```
content:
application/json:
schema:
$ref: '#/paths/~1users~1%7BuserId%7D~1alternateemails/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{\"email\": \"John.Doe@smartsheet.com\"\
}]'\n"
- lang: C#
source: "List alternateEmails = smartsheet.UserResources.AddAlternateEmail(\n\
\ 4495214342629252, // userId\n new AlternateEmail[]\
\ { // Array of AlternateEmail\n new AlternateEmail\
\ { Email = \"John.Doe@smartsheet.com\" },\n new AlternateEmail { Email\
\ = \"John.Doe.Test@smartsheet.com\" }\n }\n);\n"
- lang: Java
source: "AlternateEmail alias1 = new AlternateEmail();\nalias1.setEmail(\"\
John.Doe@smartsheet.com\");\nAlternateEmail alias2 = new AlternateEmail();\n\
alias2.setEmail(\"John.Doe.Test@smartsheet.com\");\n\nsmartsheet.userResources().addAlternateEmail(\n\
\ 4495214342629252L, // long userId\n Arrays.asList(alias1,\
\ alias2)\n );\n"
- lang: JavaScript
source: "// Specify email addresses to add\nvar body = [\n {\n email:\
\ \"John.Doe@smartsheet.com\"\n }\n];\n\n// Set options\nvar options =\
\ {\n userId: 4495214342629252,\n body: body\n};\n\n// Add alternate email\
\ address\nsmartsheet.users.addAlternateEmail(options)\n .then(function(results)\
\ {\n console.log(results);\n })\n .catch(function(error) {\n console.log(error);\n\
\ });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Users.add_alternate_email(\n 4495214342629252,\
\ # user_id\n [\n smartsheet.models.AlternateEmail({\n \
\ 'email': 'John.Doe@smartsheet.com'\n })\n ]\n)\n"
- lang: Ruby
source: "# Set options\nbody = [\n {\n email: 'John.Doe@smartsheet.com'\n\
\ }\n]\n\n# Add alternate email addresses\nresponse = smartsheet.users.alternate_emails.add(\n\
\ user_id: 4495214342629252,\n body: body\n)\n"
/users/{userId}/alternateemails/{alternateEmailId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1groups~1%7BgroupId%7D~1members~1%7BuserId%7D/parameters/2'
- name: alternateEmailId
description: Alternate Email Id
in: path
required: true
schema:
type: number
get:
operationId: get-alternate-email
summary: Get Alternate Email
description: Gets the specified alternate email.
tags:
- alternateEmailAddress
security:
- APIToken: []
- OAuth2:
- READ_USERS
responses:
'200':
description: |
Returns [AlternateEmail object](/section/AlternateEmail-Object)
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfile/properties/alternateEmails'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternateEmailId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "smartsheet.UserResources.GetAlternateEmail(\n 401090454808452, \
\ // long userId\n 123456789012345 // long altEmailId\n);\n"
- lang: Java
source: "smartsheet.userResources().getAlternateEmail(\n 401090454808452L,\
\ // long userId\n 123456789012345L // long altEmailId\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n userId: 401090454808452,\n alternateEmailId:\
\ 123456789012345\n};\n\n// Get alternate email address\nsmartsheet.users.getAlternateEmail(options)\n\
\ .then(function(email) {\n console.log(email);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "alt_email = smartsheet_client.Users.get_alternate_email(\n 401090454808452,\
\ # user_id\n 123456789012345) # alternate_email_id\n"
- lang: Ruby
source: "alt_email = smartsheet.users.alternate_emails.get(\n user_id: 401090454808452,\n\
\ alternate_email_id: 123456789012345\n)\n"
delete:
operationId: delete-alternate-email
summary: Delete Alternate Email
description: Deletes the specified alternate email address for the specified
user.
tags:
- alternateEmailAddress
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
responses:
'200':
description: |
Returns Result object
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1users~1%7BuserId%7D~1alternateemails~1%7BalternateEmailId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternatEmailId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.UserResources.DeleteAlternateEmail(\n 401090454808452,\
\ // long userId\n 123456789012345 // long altEmailId\n\
);\n"
- lang: Java
source: "smartsheet.userResources().deleteAlternateEmail(\n 401090454808452L,\
\ // long userId\n 123456789012345L // long altEmailId\n\
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n userId: 401090454808452,\n alternateEmailId:\
\ 123456789012345\n};\n\n// Delete alternate email address\nsmartsheet.users.deleteAlternateEmail(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Users.delete_alternate_email(\n 401090454808452,\
\ # user_id\n 123456789012345) # alternate_email_id\n"
- lang: Ruby
source: "smartsheet.users.alternate_emails.delete(\n user_id: 401090454808452,\n\
\ alternate_email_id: 123456789012345\n)\n"
/users/{userId}/alternateemails/{alternateEmailId}/makeprimary:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1groups~1%7BgroupId%7D~1members~1%7BuserId%7D/parameters/2'
- $ref: '#/paths/~1users~1%7BuserId%7D~1alternateemails~1%7BalternateEmailId%7D/parameters/2'
post:
operationId: promote-alternate-email
summary: Make Alternate Email Primary
description: >
Makes the specified alternate email address to become the primary email
address for the specified user.
* **_This operation is only available to system administrators_**
The alternate email address can only be made primary if both conditions are
met:
* The primary email address domain is validated
* The alternate email address is confirmed or the alternate email address
domain is validated
tags:
- alternateEmailAddress
security:
- APIToken: []
- OAuth2:
- ADMIN_USERS
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
data:
description: list of alternate email results
type: array
items:
$ref: '#/components/schemas/UserProfile/properties/alternateEmails'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/users/{userId}/alternateemails/{alternatEmailId}/makeprimary\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST\n"
- lang: C#
source: "AlternateEmail primaryEmail = smartsheet.UserResources.PromoteAlternateEmail(\n\
\ 401090454808452, // userId\n 123456789012345 // altEmailId\n\
);\n"
- lang: Java
source: "AlternateEmail primaryEmail = smartsheet.userResources().promoteAlternateEmail(\n\
\ 401090454808452L, // long userId\n 123456789012345L \
\ // long altEmailId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n userId: 401090454808452,\n alternateEmailId:\
\ 123456789012345\n};\n\n// Make alternate email primary\nsmartsheet.users.makeAlternateEmailPrimary(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Users.promote_alternate_email(\n 401090454808452,\
\ # user_id\n 123456789012345) # alt_id\n"
- lang: Ruby
source: "response = smartsheet.users.alternate_emails.make_primary(\n user_id:\
\ 401090454808452,\n alternate_email_id: 123456789012345\n)\n"
/users/{userId}/profileimage:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1groups~1%7BgroupId%7D~1members~1%7BuserId%7D/parameters/2'
post:
operationId: update-user-profile-image
summary: Update User Profile Image
description: >
Uploads an image to the user profile.
Uploading a profile image differs from Adding an Image to a Cell in the following
ways:
* A **Content-Length** header is not required
* Allowable file types are limited to: gif, jpg, and png
* Maximum file size is determined by the following rules:
* If you have not defined a custom size and the image is larger than
1050 x 1050 pixels, Smartsheet scales the image down to 1050 x 1050
* If you have defined a custom size, Smartsheet uses that as the file
size max
* If the image is not square, Smartsheet uses a solid color to pad the image
tags:
- users
security:
- APIToken: []
- OAuth2:
- WRITE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
multipart/form-data:
schema:
type: object
properties:
name:
type: string
filename:
type: string
format: binary
application/json:
schema:
$ref: '#/paths/~1sheets~1%7BsheetId%7D~1attachments/post/requestBody/content/application~1json/schema'
responses:
'200':
description: |
Returns Result object
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
data:
description: Updated User Properties
type: array
items:
$ref: '#/paths/~1users~1%7BuserId%7D/put/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/users/{userId}/profileimage'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ image/jpeg\" \\\n-H 'Content-Disposition: attachment; filename=janeroe.jpg'\
\ \\\n-X POST \\\n--data-binary @janeroe.jpg\n"
- lang: C#
source: "User myUser = smartsheet.UserResources.AddProfileImage(\n 3173821341106052,\
\ // userId\n \"../path/to/mrgoodlookin.jpg\", // string\
\ file\n \"image/jpeg\" // string fileType (MIME)\n\
);\n"
- lang: Java
source: "try {\n User myUser = smartsheet.userResources().addProfileImage(\n\
\ 3173821341106052L, // long userId\n \"../path/to/mrgoodlookin.jpg\"\
, // String file\n \"image/jpeg\" // String\
\ fileType (MIME)\n );\n } catch (FileNotFoundException e)\
\ {\n e.printStackTrace();\n }\n"
- lang: JavaScript
source: "var options = {\n userId: 3173821341106052,\n path: '../path/to/mrgoodlookin.jpg',\n\
\ fileName: 'mrgoodlookin.jpg'\n};\n\nsmartsheet.users.addProfileImage(options)\n\
\ .then(function(result) {\n console.log(result);\n }).catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "action = smartsheet_client.Users.add_profile_image(\n 3173821341106052,\
\ # user_id (int)\n '../path/to/mrgoodlookin.jpg', # file\
\ (string)\n 'image/jpeg' # file_type (string)\n)\n"
- lang: Ruby
source: "action = smartsheet_client.users.add_profile_image_from_path(\n \
\ user_id: me[:id],\n path: '../path/to/mrgoodlookin.jpg',\n content_type:\
\ 'image/jpeg'\n )\n"
/webhooks:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
operationId: list-webhooks
summary: List Webhooks
description: Gets the list of all *webhooks* that the user owns (if a user-generated
token was used to make the request) or the list of all webhooks associated
with the third-party app (if a third-party app made the request). Items in
the response are ordered by API cient name > webhook name > creation date.
tags:
- webhooks
security:
- APIToken: []
- OAuth2:
- ADMIN_WEBHOOKS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: The List of Webhooks
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
description: list of Webhooks
type: array
items:
allOf:
- type: object
properties:
callbackUrl:
description: HTTPS URL where callbacks are sent.
type: string
example: https://www.myApp.com/webhooks
enabled:
description: Indicates whether the webhook is on (true)
or off (false). ReadOnly for POST commands.
type: boolean
example: true
events:
description: Array of the events that are subscribed
to. Currently, must be an array of size 1 that contains
the string value '\*.\*' (asterisk period asterisk),
which means "all objects" and "all events".
type: array
items:
type: string
example: '*.*'
name:
description: Webhook name.
type: string
example: Webhook for Sheet Creation
version:
description: Webhook version. Currently, the only supported
value is 1. This attribute is intended to ensure backward
compatibility as new webhook functionality is released.
For example, a webhook with a version of 1 is guaranteed
to always be sent callback objects that are compatible
with the version 1 release of webhooks.
type: number
example: 1
minimum: 1
maximum: 1
- type: object
properties:
id:
description: Webhook Id.
type: number
readOnly: true
example: 8444254503626628
apiClientId:
type: string
description: API client Id corresponding to third-party
app that created the webhook. Read-only. Only present
if webhook was created by third-party app.
readOnly: true
example: 555555
scopeObjectId:
type: number
description: Id of the object that is subscribed to.
Specified when a webhook is created and cannot be
changed.
example: 3285357287499652
apiClientName:
type: string
description: API client name corresponding to third-party
app that created the webhook. Read-only. Only present
if webhook was created by third-party app.
readOnly: true
example: Awesome Smartsheet Application
createdAt:
readOnly: true
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
disabledDetails:
description: Details about the reason the webhook was
disabled. Read-only. Only present when enabled=false.
type: string
readOnly: true
modifiedAt:
readOnly: true
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
scope:
description: Scope of the subscription. Currently, the
only supported value is sheet. Specified when a webhook
is created and cannot be changed.
type: string
example: sheet
sharedSecret:
description: Shared secret for this Webhook, randomly
generated by Smartsheet. Read-only. See [Authenticating
Callbacks](../../tag/webhooksDescription#section/Webhook-Callbacks/Authenticating-Callbacks-(optional))
for details about how this value can be used.
type: string
readOnly: true
example: 216ejjzdnq17mq1q8xs7d4hu8b
stats:
type: object
readOnly: true
properties:
lastCallbackAttempt:
type: string
format: date-time
readOnly: true
description: When this webhook last made a callback
attempt.
lastCallbackAttemptRetryCount:
type: number
readOnly: true
description: The number of retries the webhook had
performed as of the last callback attempt.
lastSuccessfulCallback:
type: string
format: date-time
readOnly: true
description: When this webhook last made a successful
callback.
status:
description: Webhook status. Read-only. See Webhook
Status for list of possible values.
type: string
readOnly: true
enum:
- DISABLED_ADMINISTRATIVE
- DISABLED_APP_REVOKED
- DISABLED_BY_OWNER
- DISABLED_CALLBACK_FAILED
- DISABLED_SCOPE_INACCESSIBLE
- DISABLED_VERIFICATION_FAILED
- ENABLED
- NEW_NOT_VERIFIED
example: ENABLED
subscope:
description: Array of column Ids if you want to limit
the subscription to a subscope. Specified when a webhook
is created and cannot be changed.
type: array
items:
type: number
example:
columnIds:
- 7960873114331012
- 8731310160793142
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/webhooks \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult webhooks\
\ = smartsheet.WebhookResources.ListWebhooks(\n null // PaginationParameters\n\
);"
- lang: Java
source: "// Omit pagination parameters\nPagedResult webhooks = smartsheet.webhookResources().listWebhooks(\n\
\ null // PaginationParameters\n);"
- lang: JavaScript
source: "// Set options\nvar options = {\n};\n\n// List webhooks\nsmartsheet.webhooks.listWebhooks(options)\n\
\ .then(function(webhookList) {\n console.log(webhookList);\n\
\ })\n .catch(function(error) {\n console.log(error);\n \
\ });"
label: Node.js
- lang: Python
source: "IndexResult = smartsheet_client.Webhooks.list_webhooks(\n page_size=100,\n\
\ page=1,\n include_all=False\n)"
- lang: Ruby
source: "response = smartsheet.webhooks.list\nwebhooks = response[:data]"
post:
summary: Create Webhook
description: >
Creates a new Webhook.
A webhook is not enabled by default when it is created.
Once you've created a webhook, you can enable it by using the Update Webhook
operation to set **enabled** to **true**.
When a row is deleted on a sheet, even if you are using a **subscope** to
monitor columns only
and the cell in that column for that row is empty, you will receive a "row.deleted"
event.
operationId: createWebhook
tags:
- webhooks
security:
- APIToken: []
- OAuth2:
- ADMIN_WEBHOOKS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1webhooks/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
- type: object
required:
- callbackUrl
- events
- name
- scope
- scopeObjectId
- version
responses:
'200':
description: Result object, containing a Webhook object for the newly created
webhook
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1webhooks/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
default:
description: Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1webhooks/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/webhooks \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X POST \\\n-d '{ \"name\": \"Webhook #4\", \"callbackUrl\": \"\
https://www.myApp.com/webhooks\", \"scope\": \"sheet\", \"scopeObjectId\"\
: 3285357287499652, \"events\": [\"*.*\"], \"version\": 1, \"subscope\"\
: {\"columnIds\": [7318427511613316, 7318427511613123]}}'"
- lang: C#
source: "// Webhook specification\nWebhook webhook = new Webhook\n{\n Name\
\ = \"Webhook #4\",\n CallbackUrl = \"https://www.myApp.com/webhooks\"\
,\n Scope = \"sheet\",\n ScopeObjectId = 3285357287499652,\n Events\
\ = new string[] { \"*.*\" },\n Version = 1\n};\n\n// Create Webhook\n\
Webhook newWebhook = smartsheet.WebhookResources.CreateWebhook(\n webhook\n\
);"
- lang: Java
source: "// Webhook specification\nWebhook webhook = new Webhook();\nwebhook.setCallbackUrl(\"\
https://www.myApp.com/webhooks\")\n .setScope(\"sheet\")\n .setScopeObjectId(3285357287499652L)\n\
\ .setEvents(Arrays.asList(\"*.*\"))\n .setVersion(1)\n .setName(\"\
Webhook #4\");\n\n// Create Webhook\nWebhook newWebhook = smartsheet.webhookResources().createWebhook(\n\
\ webhook\n);"
- lang: JavaScript
source: "// Specify webhook details\nvar body = {\n name: \"Webhook #4\"\
,\n callbackUrl: \"https://www.myApp.com/webhooks\",\n scope: \"sheet\"\
,\n scopeObjectId: 3285357287499652,\n events: [\"*.*\"],\n version:\
\ 1,\n};\n\n// Set options\nvar options = {\n body: body,\n};\n\n// Create\
\ webhook\nsmartsheet.webhooks.createWebhook(options)\n .then(function(newWebhook)\
\ {\n console.log(newWebhook);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "Webhook = smartsheet_client.Webhooks.create_webhook(\n smartsheet.models.Webhook({\n\
\ 'name': 'Webhook #4',\n 'callbackUrl': 'https://www.myApp.com/webhooks',\n\
\ 'scope': 'sheet',\n 'scopeObjectId': 3285357287499652,\n 'events':\
\ ['*.*'],\n 'version': 1}))"
- lang: Ruby
source: "# Webhook specification\nbody = {\n name: 'Webhook #4',\n callback_url:\
\ 'https://www.myApp.com/webhooks',\n scope: 'sheet',\n scope_object_id:\
\ 3285357287499652,\n events: [\n '*.*'\n ],\n version: 1\n}\n\nresponse\
\ = smartsheet.webhooks.create(\n body: body\n)\nnew_webhook = response[:result]"
/webhooks/{webhookId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: webhookId
in: path
required: true
description: The Id of a Webhook
schema:
type: string
get:
summary: Get Webhook
description: Gets a Webhook based on the specified ID
operationId: getWebhook
tags:
- webhooks
security:
- APIToken: []
- OAuth2:
- ADMIN_WEBHOOKS
responses:
'200':
description: Webhook object
content:
application/json:
schema:
$ref: '#/paths/~1webhooks/get/responses/200/content/application~1json/schema/allOf/1/properties/data/items'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/webhooks/{webhookId} \\\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\""
- lang: C#
source: "Webhook webhook = smartsheet.WebhookResources.GetWebhook(\n 401090454808452\
\ // long webhookId\n);"
- lang: Java
source: "Webhook webhook = smartsheet.webhookResources().getWebhook(\n \
\ 401090454808452L // long webhookId\n);"
- lang: JavaScript
source: "// Set options\nvar options = {\n webhookId: 401090454808452\n\
};\n\n// Get webhook\nsmartsheet.webhooks.getWebhook(options)\n .then(function(webhook)\
\ {\n console.log(webhook);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });;"
label: Node.js
- lang: Python
source: "Webhook = smartsheet_client.Webhooks.get_webhook(\n 401090454808452)\
\ # webhook_id"
- lang: Ruby
source: "Webhook = smartsheet.webhooks.get(\n webhook_id: 2674017481058180\n\
)"
put:
summary: Update Webhook
description: >
Updates the specified Webhook. The following properties can be updated:
* callbackUrl (optional)
* enabled (optional)
* events (optional)
* name (optional)
* version (optional)
When setting a webhook's **enabled** to **true** using this operation,
the behavior and result depend on the webhook's **status** and may result
in a webhook verification being triggered,
or in some cases, an error being returned. See Webhook Status for more details.
operationId: updateWebhook
tags:
- webhooks
security:
- APIToken: []
- OAuth2:
- ADMIN_WEBHOOKS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
content:
application/json:
schema:
type: object
properties:
callbackUrl:
description: HTTPS URL where callbacks are sent.
type: string
example: https://www.myApp.com/webhooks
enabled:
description: Indicates whether the webhook is on (true) or off (false).
ReadOnly for POST commands.
type: boolean
example: true
events:
description: Array of the events that are subscribed to. Currently,
must be an array of size 1 that contains the string value '\*.\*'
(asterisk period asterisk), which means "all objects" and "all
events".
type: array
items:
type: string
example: '*.*'
name:
description: Webhook name.
type: string
example: Webhook for Sheet Creation
version:
description: Webhook version. Currently, the only supported value
is 1. This attribute is intended to ensure backward compatibility
as new webhook functionality is released. For example, a webhook
with a version of 1 is guaranteed to always be sent callback objects
that are compatible with the version 1 release of webhooks.
type: number
example: 1
minimum: 1
maximum: 1
responses:
'200':
description: Result object containing the Webhook object for the updated
webhook
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1webhooks~1%7BwebhookId%7D/get/responses/200/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/webhooks/{webhookId} \\\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{ \"enabled\": true }"
- lang: C#
source: "// Webhook specification\nWebhook webhook = new Webhook\n{\n Id\
\ = 8444254503626628,\n CallbackUrl = \"https://www.myApp.com/webhooks\"\
,\n Version = 1,\n Enabled = true\n}\n\n// Update Webhook\nWebhook\
\ updatedWebhook = smartsheet.WebhookResources.UpdateWebhook(\n webhook\n\
);"
- lang: Java
source: "// Webhook specification\nWebhook webhook = new Webhook();\n webhook.setCallbackUrl(\"\
https://www.myApp.com/webhooks\")\n .setVersion(1)\n .setEnabled(true)\n\
\ .setId(8444254503626628L);\n\n// Update Webhook\nWebhook updatedWebhook\
\ = smartsheet.webhookResources().updateWebhook(\n webhook\n);"
- lang: JavaScript
source: "// Specify changed values\nvar body = {\n enabled: true\n};\n\n\
// Set options\nvar options = {\n webhookId: 8444254503626628,\n body:\
\ body\n};\n\n// Update webhook\nsmartsheet.webhooks.updateWebhook(options)\n\
\ .then(function(updatedWebhook) {\n console.log(updatedWebhook);\n\
\ })\n .catch(function(error) {\n console.log(error);\n \
\ });"
label: Node.js
- lang: Python
source: "Webhook = smartsheet_client.Webhooks.update_webhook(\n 8444254503626628,\
\ # webhook_id\n smartsheet_client.models.Webhook({\n 'enabled':\
\ True}))"
- lang: Ruby
source: "# Webhook specification\nbody = {\n name: 'Webhook #4',\n callback_url:\
\ 'https://www.myApp.com/webhooks/nouveau',\n events: [\n '*.*'\n ],\n\
\ enabled: true,\n version: 1\n}\n\n# Update Webhook\nresponse = smartsheet.webhooks.update(\n\
\ webhook_id: 8444254503626628,\n body: body\n)\nupdated_webhook = response[:result]"
delete:
summary: Delete Webhook
description: >
Deletes the specified Webhook.
Using this operation permanently deletes the specified webhook.
To temporarily disable a webhook, use the Update Webhook operation to set
**enabled** to **false**.
operationId: deleteWebhook
tags:
- webhooks
security:
- APIToken: []
- OAuth2:
- ADMIN_WEBHOOKS
responses:
'200':
description: Result object
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1webhooks~1%7BwebhookId%7D/put/responses/200/content/application~1json/schema/allOf/0'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/webhooks/{webhookId} \\\n-H \"\
Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE"
- lang: C#
source: "smartsheet.WebhookResources.DeleteWebhook(\n 401090454808452 \
\ // long webhookId\n);"
- lang: Java
source: "smartsheet.webhookResources().deleteWebhook(\n 401090454808452L\
\ // long webhookId\n);"
- lang: JavaScript
source: "// Set options\nvar options = {\n webhookId: 401090454808452\n\
};\n\n// Delete webhook\nsmartsheet.webhooks.deleteWebhook(options)\n \
\ .then(function(results) {\n console.log(results);\n })\n \
\ .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "smartsheet_client.Webhooks.delete_webhook(\n 401090454808452) \
\ # webhook_id"
- lang: Ruby
source: "smartsheet.webhooks.delete(\n webhook_id: 2674017481058180\n)"
/webhooks/{webhookId}/resetSharedSecret:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1webhooks~1%7BwebhookId%7D/parameters/1'
post:
summary: Reset Shared Secret
description: >-
Resets the shared secret for the specified webhook. For more information
about how a shared secret is used, see Authenticating Callbacks.
This operation can be used to rotate an API client's webhooks' shared secrets
at periodic intervals to provide additional security.
operationId: resetSharedSecret
tags:
- webhooks
security:
- APIToken: []
- OAuth2:
- ADMIN_WEBHOOKS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: object
properties:
sharedSecret:
description: Value for the shared secret.
type: string
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/webhooks/{webhookId}/resetsharedsecret\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST"
- lang: C#
source: "WebhookSharedSecret newSecret = smartsheet.WebhookResources.ResetSharedSecret(\n\
\ 401090454808452 // long webhookId\n);"
- lang: Java
source: "WebhookSharedSecret newSecret = smartsheet.webhookResources().ResetSharedSecret(\n\
\ 401090454808452L // long webhookId\n);"
- lang: JavaScript
source: "// Get options\nvar options = {\n webhookId: 401090454808452\n\
};\n\n// Reset shared secret\nsmartsheet.webhooks.resetSharedSecret(options)\n\
\ .then(function(newSecret) {\n console.log(newSecret);\n })\n\
\ .catch(function(error) {\n console.log(error);\n });"
label: Node.js
- lang: Python
source: "Webhook = smartsheet_client.Webhooks.reset_shared_secret(\n 401090454808452)\
\ # webhook_id"
- lang: Ruby
source: "response = smartsheet.webhooks.reset_shared_secret(\n webhook_id:\
\ 401090454808452\n)\nupdated_secret = response[:result]"
/workspaces:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: List Workspaces
description: >
Gets a list of workspaces that the user has access to. The list contains
an abbreviated Workspace object for each workspace.
tags:
- workspaces
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: list-workspaces
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: IndexResult object containing an array of Workspace objects.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Home/properties/workspaces/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult workspaces\
\ = smartsheet.WorkspaceResources.ListWorkspaces(\n null \
\ // PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult workspaces\
\ = smartsheet.workspaceResources().listWorkspaces(\n null \
\ // PaginationParameters\n );\n"
- lang: JavaScript
source: "smartsheet.workspaces.listWorkspaces()\n\t.then(function(workspaceList)\
\ {\n\t\tconsole.log(workspaceList);\n\t})\n\t.catch(function(error) {\n\
\t\tconsole.log(error);\n\t});\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Workspaces.list_workspaces(include_all=True)\n\
workspaces = response.data\n\n# Sample 2: Paginate the list\nresponse =\
\ smartsheet_client.Workspaces.list_workspaces(\n page_size=20,\n page=1)\n\
pages = response.total_pages\nworkspaces = response.data\n"
- lang: Ruby
source: "response = smartsheet.workspaces.list\nworkspaces = response[:data]\n"
post:
summary: Create Workspace
description: |
Creates a new workspace.
operationId: create-workspace
tags:
- workspaces
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- name: include
in: query
required: false
description: >
A comma-separated list of elements to include:
* **all**
* **attachments**
* **brand**
* **cellLinks** - includes cross-sheet references
* **data** - includes formatting
* **discussions** - includes comments
* **filters**
* **forms**
* **ruleRecipients**
* **rules**
* **shares**
NOTE: Cell history is not copied, regardless of which include parameter
values are specified.
schema:
type: string
enum:
- all
- attachments
- brand
- cellLinks
- data
- discussions
- filters
- forms
- ruleRecipients
- rules
- shares
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/parameters/3'
requestBody:
description: Workspace to create.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1workspaces/get/responses/200/content/application~1json/schema/allOf/1/properties/result/items'
responses:
'200':
description: Result object containing a Workspace object for newly created
workspace.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1workspaces/get/responses/200/content/application~1json/schema/allOf/1/properties/result/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1workspaces/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces \\\n-H \"Authorization:\
\ Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type: application/json\"\
\ \\\n-X POST \\\n-d '{\"name\": \"New workspace\"}'\n"
- lang: C#
source: "// Specify workspace name\nWorkspace workspaceSpecification = new\
\ Workspace { Name = \"New workspace\" };\n\n// Create workspace\nWorkspace\
\ newWorkspace = smartsheet.WorkspaceResources.CreateWorkspace(workspaceSpecification);\n"
- lang: Java
source: "// Specify workspace name\nWorkspace workspaceSpecification = new\
\ Workspace();\nworkspaceSpecification.setName(\"New workspace\");\n\n//\
\ Create workspace\nWorkspace newWorkspace = smartsheet.workspaceResources().createWorkspace(workspaceSpecification);\n"
- lang: JavaScript
source: "// Specify workspace name\nvar workspace = {\"name\": \"New workspace\"\
};\n\n// Set options\nvar options = {\n body: workspace\n};\n\n// Create\
\ workspace\nsmartsheet.workspaces.createWorkspace(options)\n .then(function(newWorkspace)\
\ {\n console.log(newWorkspace);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "workspace = smartsheet_client.Workspaces.create_workspace(\n smartsheet.models.Workspace({\n\
\ 'name': 'New workspace'\n })\n)\n"
- lang: Ruby
source: "# Specify details\nbody = {\n name: 'New workspace'\n}\n\n# Create\
\ the workspace\nresponse = smartsheet.workspaces.create(\n body: body\n\
)\nworkspace = response[:result]\n"
/workspaces/{workspaceId}:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- name: workspaceId
in: path
schema:
type: string
required: true
description: WorkspaceID of the sheet being accessed.
get:
summary: Get Workspace
description: Gets a Workspace object.
tags:
- workspaces
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: get-workspace
parameters:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/get/parameters/0'
- name: loadAll
in: query
required: false
description: Set to **true** to see nested folders. A value of **false** returns
top-level folders only.
schema:
type: boolean
default: false
responses:
'200':
description: A single Workspace object.
content:
application/json:
schema:
$ref: '#/components/schemas/Home/properties/workspaces/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/{workspaceid} \\\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Sample 1: Omit 'loadAll' and 'include' parameters\nWorkspace workspace\
\ = smartsheet.WorkspaceResources.GetWorkspace(\n 6621332407379844, \
\ // long workspaceId\n null, // Nullable\
\ loadAll,\n null // IEnumerable\
\ include\n);\n\n// Sample 2: Specify 'loadAll' parameter with value of\
\ \"false\", and 'include' parameter with value of \"source\"\nWorkspace\
\ workspace = smartsheet.WorkspaceResources.GetWorkspace(\n 6621332407379844,\
\ // long workspaceId\n false, // Nullable\
\ loadAll,\n new WorkspaceInclusion[] { WorkspaceInclusion.SOURCE }\n);\n"
- lang: Java
source: "// Sample 1: Omit 'loadAll' and 'include' parameters\nWorkspace workspace\
\ = smartsheet.workspaceResources().getWorkspace(\n 6621332407379844L,\
\ // long workspaceId\n null, // Boolean loadAll\n\
\ null // EnumSet includes\n\
\ );\n\n// Sample 2: Specify 'loadAll' parameter with value of \"\
false\", and 'include' parameter with value of \"source\"\nWorkspace workspace\
\ = smartsheet.workspaceResources().getWorkspace(\n 6621332407379844L,\
\ // long workspaceId\n false, // Boolean loadAll\n\
\ EnumSet.of(SourceInclusion.SOURCE)\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n workspaceId: 7116448184199044\n\
};\n\n// Get workspace\nsmartsheet.workspaces.getWorkspace(options)\n .then(function(workspace)\
\ {\n console.log(workspace);\n })\n .catch(function(error) {\n \
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "workspace = smartsheet_client.Workspaces.get_workspace(\n 6621332407379844)\
\ # workspace_id\n"
- lang: Ruby
source: "response = smartsheet.workspaces.get(\n workspace_id: 7116448184199044\n\
)\n"
delete:
summary: Delete Workspace
description: Deletes a workspace.
tags:
- workspaces
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
operationId: delete-workspace
responses:
'200':
description: |
Returns Result object
content:
application/json:
schema:
$ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/7960873114331012 \\\
\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.WorkspaceResources.DeleteWorkspace(\n 6621332407379844\
\ // long workspaceId\n);\n"
- lang: Java
source: "smartsheet.workspaceResources().deleteWorkspace(\n 6621332407379844L\
\ // long workspaceId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n workspaceId: 6621332407379844\n\
};\n\n// Delete workspace\nsmartsheet.workspaces.deleteWorkspace(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Workspaces.delete_workspace(\n 6621332407379844)\
\ # workspace_id\n"
- lang: Ruby
source: "smartsheet.workspaces.delete(\n workspace_id: 7116448184199044\n\
)\n"
put:
summary: Update Workspace
description: Updates a workspace.
operationId: update-workspace
tags:
- workspaces
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
requestBody:
content:
application/json:
schema:
description: schema for updating workspaces
type: object
properties:
name:
description: Workspace name.
type: string
responses:
'200':
description: Result object containing the modified Workspace object.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/7960873114331012 \\\
\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{\"name\": \"Updated workspace\"\
}'\n"
- lang: C#
source: "// Specify updated workspace name\nWorkspace workspaceSpecification\
\ = new Workspace\n{\n Id = 7960873114331012, // workspaceId\n Name\
\ = \"Updated Workspace\"\n};\n\n// Update workspace\nWorkspace updatedWorkspace\
\ = smartsheet.WorkspaceResources.UpdateWorkspace(\n workspaceSpecification\n\
);\n"
- lang: Java
source: "// Specify updated workspace properties\nWorkspace workspaceSpecification\
\ = new Workspace();\nworkspaceSpecification.setName(\"Updated workspace\"\
)\n .setId(7960873114331012L); // long workspaceId\n\n// Update\
\ workspace\nWorkspace updatedWorkspace = smartsheet.workspaceResources().updateWorkspace(workspaceSpecification);\n"
- lang: JavaScript
source: "// Specify updated workspace properties\nvar workspace = {\"name\"\
: \"Updated workspace\"};\n\n// Set options\nvar options = {\n workspaceId:\
\ 7960873114331012,\n body: workspace\n };\n\n// Update workspace\nsmartsheet.workspaces.updateWorkspace(options)\n\
\ .then(function(updatedWorkspace) {\n console.log(updatedWorkspace);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_workspace = smartsheet_client.Workspaces.update_workspace(\n\
\ 7960873114331012, # workspace_id\n smartsheet.models.Workspace({\n\
\ 'name': 'Updated workspace'\n })\n)\n"
- lang: Ruby
source: "# Specify updated workspace properties\nbody = {\n name: 'Updated\
\ workspace'\n}\n\n# Update workspace\nresponse = smartsheet.workspaces.update(\n\
\ workspace_id: 7960873114331012,\n body: body\n)\n"
/workspaces/{workspaceId}/copy:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/parameters/1'
post:
summary: Copy Workspace
description: Copies a workspace.
tags:
- workspaces
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
operationId: copy-workspace
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1workspaces/post/parameters/1'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/parameters/3'
requestBody:
description: New workspace name.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1copy/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: Result object containing a Workspace object for the new workspace
destination.
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1copy/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/workspaces/{workspaceId}/copy?include=data'\n\
-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n-H \"Content-Type:\
\ application/json\"\n-d '{\"newName\": \"newWorkspaceName\"}'\n-X POST\n"
- lang: C#
source: "// Specify name for the new workspace\nContainerDestination destination\
\ = new ContainerDestination {\n NewName = \"newWorkspaceName\"\n};\n\n\
// Sample 1: Omit 'include' and 'skipRemap' parameters\nWorkspace workspace\
\ = smartsheet.WorkspaceResources.CopyWorkspace(\n 7116448184199044, \
\ // long workspaceId\n destination,\n null, \
\ // IEnumerable include\n null \
\ // IEnumerable skipRemap\n);\n\n//\
\ Sample 2: Specify 'include' parameter with value of \"DATA\", and 'skipRemap'\
\ parameter with value of \"CELL_LINKS\"\nWorkspace workspace = smartsheet.WorkspaceResources.CopyWorkspace(\n\
\ 7116448184199044, // long workspaceId\n destination,\n new\
\ WorkspaceCopyInclusion[] { WorkspaceCopyInclusion.DATA },\n new WorkspaceRemapExclusion[]\
\ { WorkspaceRemapExclusion.CELL_LINKS }\n);\n"
- lang: Java
source: "// Specify name for the new workspace\nContainerDestination destination\
\ = new ContainerDestination();\ndestination.setNewName(\"newWorkspaceName\"\
);\n\n// Sample 1: Omit 'include' and 'skipRemap' parameters\nWorkspace\
\ workspace = smartsheet.workspaceResources().copyWorkspace(\n 7116448184199044L,\
\ // long workspaceId\n destination,\n null, \
\ // EnumSet includes\n \
\ null // EnumSet skipRemap\n\
\ );\n\n// Sample 2: Specify 'include' parameter with value of \"\
DATA\", and 'skipRemap' parameter with value of \"CELLLINKS\"\nWorkspace\
\ workspace = smartsheet.workspaceResources().copyWorkspace(\n 7116448184199044L,\
\ // long workspaceId\n destination,\n EnumSet.of(WorkspaceCopyInclusion.DATA),\n\
\ EnumSet.of(WorkspaceRemapExclusion.CELLLINKS)\n );\n"
- lang: JavaScript
source: "// Specify new workspace name\nvar body = {\n newName: \"newWorkspaceName\"\
\n};\n\n// Set elements to copy\nvar params = {\n include: \"data,discussions\"\
,\n skipRemap: \"cellLinks\"\n};\n\n// Set options\nvar options = {\n \
\ workspaceId: 7116448184199044,\n body: body,\n queryParameters: params\n\
};\n\n// Copy workspace\nsmartsheet.workspaces.copyWorkspace(options)\n\
\ .then(function(copiedWorkspace) {\n console.log(copiedWorkspace);\n\
\ })\n .catch(function(error) {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "new_workspace = smartsheet_client.Workspaces.copy_workspace(\n 7116448184199044,\
\ # workspace_id\n smartsheet.models.ContainerDestination({\n\
\ 'new_name': 'newWorkspaceName'\n })\n)\n"
- lang: Ruby
source: "# Specify details\nbody = {\n new_name: 'newWorkspaceName'\n}\n\n\
# Copy workspace\nresponse = smartsheet.workspaces.copy(\n workspace_id:\
\ 7116448184199044,\n body: body\n)\nnew_workspace = response[:result]\n"
/workspaces/{workspaceId}/folders:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/parameters/1'
get:
summary: Get Workspace folders
description: Gets a workspace's folders.
tags:
- workspaces
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
operationId: get-workspace-folders
parameters:
- $ref: '#/paths/~1contacts/get/parameters/0'
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
responses:
'200':
description: An array of Folder objects.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Folder/properties/folders/items'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/folders\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult folders =\
\ smartsheet.WorkspaceResources.FolderResources.ListFolders(\n 1656220827314052,\
\ // long workspaceId\n null //\
\ PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult folders = smartsheet.workspaceResources().folderResources().listFolders(\n\
\ 1656220827314052L, // long workspaceId\n \
\ null // PaginationParameters\n \
\ );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n workspaceId: 1656220827314052\n\
};\n\n// List folders in workspace\nsmartsheet.workspaces.listWorkspaceFolders(options)\n\
\ .then(function(folderList) {\n console.log(folderList);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Workspaces.list_folders(\n\
\ 1656220827314052, # workspace_id\n include_all=True)\nfolders\
\ = response.data\n\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Workspaces.list_folders(\n\
\ 1656220827314052, # workspace_id\n page_size=5,\n page=1)\npages\
\ = response.total_pages\nfolders = response.data\n"
- lang: Ruby
source: "response = smartsheet.folders.list_in_workspace(\n workspace_id:\
\ 1656220827314052\n)\nfolders = response[:data]\n"
post:
summary: Create a Folder
description: |
Creates a new folder.
operationId: create-workspace-folder
tags:
- workspaces
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
requestBody:
description: Folder to create.
required: true
content:
application/json:
schema:
description: Can contain dashboards, folders, reports, sheets, or templates.
type: object
properties:
name:
description: Folder name.
type: string
responses:
'200':
description: Result object containing a Folder object for newly created
folder.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
description: Can contain dashboards, folders, reports, sheets,
or templates.
type: object
properties:
name:
description: Folder name.
type: string
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1folders/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/{workspaceid}/folders\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"name\": \"New folder\"}'\n"
- lang: C#
source: "// Set folder name\nFolder folderSpecification = new Folder { Name\
\ = \"New folder\" };\n\n// Create folder in a workspace\nFolder newFolder\
\ = smartsheet.WorkspaceResources.FolderResources.CreateFolder(\n 1656220827314052,\
\ // long workspaceId\n folderSpecification\n);\n"
- lang: Java
source: "// Set folder name\nFolder folderSpecification = new Folder();\n\
folderSpecification.setName(\"New Folder\");\n\n// Create folder in a workspace\n\
Folder newFolder = smartsheet.workspaceResources().folderResources().createFolder(\n\
\ 1656220827314052L, // long workspaceId\n folderSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Set folder name\nvar folder = {\n \"name\": \"New folder\"\n\
};\n\n// Set options\nvar options = {\n workspaceId: 1656220827314052,\n\
\ body: folder\n };\n\n// Create folder in a workspace\nsmartsheet.workspaces.createFolder(options)\n\
\ .then(function(newFolder) {\n console.log(newFolder);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "new_workspace = smartsheet_client.Workspaces.create_folder_in_workspace(\n\
\ 1656220827314052, # workspace_id\n 'New folder')\n"
- lang: Ruby
source: "body = {\n name: 'New Folder'\n}\n\nnew_folder = smartsheet.folders.create_in_workspace(\n\
\ workspace_id: 1656220827314052,\n body: body\n)\n"
/workspaces/{workspaceId}/shares:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/parameters/1'
post:
summary: Share Workspace
description: >
Shares a Workspace with the specified users and groups. This operation
supports both single-object and bulk semantics.
operationId: share-workspace
tags:
- sharing
- workspaces
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
parameters:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/parameters/0'
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
- type: array
items:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
responses:
'200':
description: >
This operation supports both single-object and bulk semantics. For
more information, see Optional Bulk Operations.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
- type: array
items:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
'400':
description: >
If called with a single Share object, and that user or group share
already exists, error code 1025 is returned.
If called with an array of Share objects, and one or more user or group
shares in the array already exist,
they are ignored and omitted from the response.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares/post/responses/400/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl 'https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares?sendEmail=true'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '[{\"email\": \"jane.doe@smartsheet.com\"\
, \"accessLevel\": \"EDITOR\"}]'\n"
- lang: C#
source: "// Specify share (to one user as Editor)\nShare[] shareSpecification\
\ = new Share[] { new Share\n {\n Email = \"jane.doe@smartsheet.com\"\
,\n AccessLevel = AccessLevel.EDITOR\n }\n};\n\n// Share workspace\n\
IList addressList = smartsheet.WorkspaceResources.ShareResources.ShareTo(\n\
\ 7960873114331012, // long workspaceId\n shareSpecification,\n\
\ true // Nullable sendEmail\n);\n"
- lang: Java
source: "// Specify share (to one user as Editor)\nShare shareSpecification\
\ = new Share()\n .setEmail(\"jane.doe@smartsheet.com\")\n \
\ .setAccessLevel(AccessLevel.EDITOR);\n\n// Share workspace\nList\
\ addressList = smartsheet.workspaceResources().shareResources().shareTo(\n\
\ 7960873114331012L, // long workspaceId\n \
\ (Arrays.asList(shareSpecification)),\n true \
\ // Boolean sendEmail\n );\n"
- lang: JavaScript
source: "// Specify share (to one user as Editor)\nvar shares = [\n\t{\n\t\
\t\"email\": \"john.doe@smartsheet.com\",\n\t\t\"accessLevel\": \"EDITOR\"\
\n\t}\n];\n\n// Set options\nvar options = {\n\tworkspaceId: 7960873114331012,\n\
\tbody: shares\n};\n\n// Share workspace\nsmartsheet.workspaces.share(options)\n\
\t.then(function(addressList) {\n\t\tconsole.log(addressList);\n\t})\n\t\
.catch(function(error) {\n\t\tconsole.log(error);\n\t});\n"
label: Node.js
- lang: Python
source: "response = smartsheet_client.Workspaces.share_workspace(\n 1656220827314052,\
\ # workspace_id\n smartsheet.models.Share({\n 'access_level':\
\ 'EDITOR',\n 'email': 'jane.doe@smartsheet.com'\n })\n)\n"
- lang: Ruby
source: "body = {\n email: 'jane.doe@smartsheet.com',\n access_level: 'EDITOR',\n\
\ subject: 'This workspace has been shared with you!',\n message: 'This\
\ Smartsheet workspace is ready for your inspection.'\n}\n\nresponse = smartsheet.workspaces.share.create(\n\
\ workspace_id: 1656220827314052,\n body: body\n)\n"
get:
summary: List Workspace Shares
description: Gets a list of all users and groups to whom the specified Workspace
is shared, and their access level.
operationId: list-workspace-shares
tags:
- sharing
- workspaces
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
parameters:
- $ref: '#/paths/~1contacts/get/parameters/3'
- $ref: '#/paths/~1contacts/get/parameters/4'
- $ref: '#/paths/~1contacts/get/parameters/0'
responses:
'200':
description: IndexResult object containing an array of Share objects.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1contacts/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
result:
type: array
items:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares/post/responses/400/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "// Omit pagination parameters\nPaginatedResult shares = smartsheet.WorkspaceResources.ShareResources.ListShares(\n\
\ 1656220827314052, // long workspaceId\n null \
\ // PaginationParameters\n);\n"
- lang: Java
source: "// Omit pagination parameters\nPagedResult shares = smartsheet.workspaceResources().shareResources().listShares(\n\
\ 1656220827314052L, // long workspaceId\n null, \
\ // PaginationParameters\n true \
\ // Boolean includeWorkspaceShares\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n workspaceId: 1656220827314052\n\
};\n\n// List workspace shares\nsmartsheet.workspaces.listShares(options)\n\
\ .then(function(shareList) {\n console.log(shareList);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "# Sample 1: List all\nresponse = smartsheet_client.Workspaces.list_shares(\n\
\ 1656220827314052, # workspace_id\n include_all=True)\nshares =\
\ response.data\n\n# Sample 2: Paginate the list\nresponse = smartsheet_client.Workspaces.list_shares(\n\
\ 1656220827314052, # workspace_id\n page_size=10,\n page=1)\n\
pages = response.total_pages\nshares = response.data\n"
- lang: Ruby
source: "response = smartsheet.workspaces.share.list(\n workspace_id: 1656220827314052\n\
)\nshares = response[:data]\n"
/workspaces/{workspaceId}/shares/{shareId}:
parameters:
- $ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/parameters/1'
- $ref: '#/paths/~1reports~1%7BreportId%7D~1shares~1%7BshareId%7D/parameters/1'
- $ref: '#/paths/~1contacts/parameters/0'
get:
summary: Get Workspace Share.
description: Gets the share specified in the URL.
operationId: share-workspace-get
tags:
- sharing
- workspaces
security:
- APIToken: []
- OAuth2:
- READ_SHEETS
responses:
'200':
description: Returns Share object.
content:
application/json:
schema:
$ref: '#/paths/~1reports~1%7BreportId%7D~1shares/post/requestBody/content/application~1json/schema/oneOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\"\n"
- lang: C#
source: "Share share = smartsheet.WorkspaceResources.ShareResources.GetShare(\n\
\ 1656220827314052, // long workspaceId\n \"AQAISF82FOeE\" \
\ // string shareId\n);\n"
- lang: Java
source: "Share share = smartsheet.workspaceResources().shareResources().getShare(\n\
\ 1656220827314052L, // long workspaceId\n \"AQAISF82FOeE\"\
\ // string shareId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n workspaceId: 1656220827314052,\n\
\ shareId: \"AQAISF82FOeE\"\n};\n\n// Get workspace share\nsmartsheet.workspaces.getShare(options)\n\
\ .then(function(share) {\n console.log(share);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "share = smartsheet_client.Sheets.get_share(\n 1656220827314052,\
\ # workspace_id\n 'AAAEQesWFOeE') # share_id\n"
- lang: Ruby
source: "share = smartsheet.workspaces.share.get(\n workspace_id: 1656220827314052,\n\
\ share_id: 'AAABbMomFOeE'\n)\n"
delete:
summary: Delete Workspace Share
description: Deletes the share specified in the URL.
operationId: delete-workspace-share
tags:
- sharing
- workspaces
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
responses:
'200':
description: Returns Result object.
content:
application/json:
schema:
$ref: '#/paths/~1favorites/post/responses/200/content/application~1json/schema/allOf/0'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares~1%7BshareId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-X DELETE\n"
- lang: C#
source: "smartsheet.WorkspaceResources.ShareResources.DeleteShare(\n 1656220827314052,\
\ // long workspaceId\n \"AAAEQesWFOeE\" \
\ // string shareId\n);\n"
- lang: Java
source: "smartsheet.workspaceResources().shareResources().deleteShare(\n \
\ 1656220827314052L, // long workspaceId\n \"AAAEQesWFOeE\"\
\ // string shareId\n );\n"
- lang: JavaScript
source: "// Set options\nvar options = {\n workspaceId: 1656220827314052,\n\
\ shareId: \"AAAEQesWFOeE\"\n};\n\n// Delete workspace share\nsmartsheet.workspaces.deleteShare(options)\n\
\ .then(function(results) {\n console.log(results);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "smartsheet_client.Workspaces.delete_share(\n 1656220827314052, \
\ # workspace_id\n 'AAAEQesWFOeE') # share_id\n"
- lang: Ruby
source: "smartsheet.workspaces.share.delete(\n workspace_id: 1656220827314052,\n\
\ share_id: 'AAABbMomFOeE'\n)\n"
put:
summary: Update Workspace Share.
description: Updates the access level of a user or group for the specified workspace.
operationId: update-workspace-share
tags:
- sharing
- workspaces
security:
- APIToken: []
- OAuth2:
- ADMIN_WORKSPACES
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares~1%7BshareId%7D/get/responses/200/content/application~1json/schema'
responses:
'200':
description: Result object containing the modified Share object.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares~1%7BshareId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
type: object
items:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares~1%7BshareId%7D/get/responses/200/content/application~1json/schema'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/paths/~1workspaces~1%7BworkspaceId%7D~1shares~1%7BshareId%7D/get/responses/default/content/application~1json/schema'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/shares/{shareId}\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X PUT \\\n-d '{\"accessLevel\": \"VIEWER\"}'\n"
- lang: C#
source: "// Set the access level to Viewer\nShare shareSpecification = new\
\ Share\n{\n Id = \"AAAFeF82FOeE\",\n AccessLevel = AccessLevel.VIEWER\n\
};\n\n// Update workspace share\nShare updatedShare = smartsheet.WorkspaceResources.ShareResources.UpdateShare(\n\
\ 1656220827314052, // long workspaceId\n shareSpecification\n\
);\n"
- lang: Java
source: "// Set the access level to Viewer\nShare shareSpecification = new\
\ Share();\n shareSpecification.setAccessLevel(AccessLevel.VIEWER)\n\
\ .setId(\"AAAFeF82FOeE\"); // string shareId\n\n// Update workspace\
\ share\nShare updatedShare = smartsheet.workspaceResources().shareResources().updateShare(\n\
\ 1656220827314052L, // long workspaceId\n shareSpecification\n\
\ );\n"
- lang: JavaScript
source: "// Set access level to Viewer\nvar share = {\"accessLevel\": \"VIEWER\"\
};\n\n// Set options\nvar options = {\n workspaceId: 1656220827314052,\n\
\ shareId: \"AAAFeF82FOeE\",\n body: share\n };\n\n// Update workspace\
\ share\nsmartsheet.workspaces.updateShare(options)\n .then(function(updatedShare)\
\ {\n console.log(updatedShare);\n })\n .catch(function(error) {\n\
\ console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "updated_share = smartsheet_client.Workspaces.update_share(\n 1656220827314052,\
\ # workspace_id\n 'AAAFeF82FOeE', # share_id\n smartsheet.models.Share({\n\
\ 'access_level': 'VIEWER'\n })\n)\n"
- lang: Ruby
source: "body = {\n access_level: 'VIEWER'\n}\n\nresponse = smartsheet.workspaces.share.update(\n\
\ workspace_id: 1656220827314052,\n share_id: 'AAABbMomFOeE',\n body:\
\ body\n)\n"
/workspaces/{workspaceId}/sheets:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/parameters/1'
post:
summary: Create Sheet in Workspace
description: >
Creates a sheet from scratch or from the specified template at the
top-level of the specified workspace.
For subfolders, use Create Sheet in Folder.
operationId: create-sheet-in-workspace
tags:
- sheets
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
parameters:
- $ref: '#/paths/~1favorites/post/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/parameters/1'
requestBody:
description: Sheet to create.
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/requestBody/content/application~1json/schema/oneOf/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/requestBody/content/application~1json/schema/oneOf/1'
responses:
'200':
description: Result object containing a Sheet object for newly created sheet,
corresponding to what was specified in the request.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
oneOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets/post/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "// Sample 1: Create sheet in workspace\ncurl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/sheets\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"name\":\"newsheet\",\"columns\"\
:[{\"title\":\"Favorite\",\"type\":\"CHECKBOX\",\"symbol\":\"STAR\"}, {\"\
title\":\"Primary Column\", \"primary\":true,\"type\":\"TEXT_NUMBER\"}]}'\n\
\n// Sample 2: Create sheet in workspace from template\ncurl 'https://api.smartsheet.com/2.0/workspaces/{workspaceId}/sheets?include=data,attachments,discussions'\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Type:\
\ application/json\" \\\n-X POST \\\n-d '{\"name\":\"newsheet\", \"fromId\"\
: 7679398137620356}'\n"
- lang: C#
source: "// Sample 1: Create sheet in workspace\n// Specify properties of\
\ the first column\nColumn columnA = new Column\n{\n Title = \"Favorite\"\
,\n Primary = false,\n Type = ColumnType.CHECKBOX,\n Symbol = Symbol.STAR\n\
};\n\n// Specify properties of the second column\nColumn columnB = new Column\n\
{\n Title = \"Primary Column\",\n Primary = true,\n Type = ColumnType.TEXT_NUMBER\n\
};\n\n// Create sheet in workspace (specifying the 2 columns to include\
\ in the sheet)\nSheet newSheet = smartsheet.WorkspaceResources.SheetResources.CreateSheet(\n\
\ 3734419270854532, // long workspaceId\n new Sheet\n\
\ {\n Name = \"new sheet title\",\n Columns = new Column[]\
\ { columnA, columnB }\n }\n);\n\n// Sample 2: Create sheet in workspace\
\ from template\n// Specify name for the sheet and Id of the template\n\
Sheet sheetSpecification = new Sheet\n{\n Name = \"new sheet title\",\n\
\ FromId = 7679398137620356 // template Id\n};\n\n// Option 1: Omit\
\ 'include' parameter\nSheet newSheet = smartsheet.WorkspaceResources.SheetResources.CreateSheetFromTemplate(\n\
\ 1656220827314052, // long workspaceId\n sheetSpecification,\n\
\ null // IEnumerable include\n\
);\n\n// Option 2: Include ATTACHMENTS, DATA, and DISCUSSIONS\nSheet newSheet\
\ = smartsheet.WorkspaceResources.SheetResources.CreateSheetFromTemplate(\n\
\ 1656220827314052, // long workspaceId\n sheetSpecification,\n\
\ new TemplateInclusion[] {\n TemplateInclusion.ATTACHMENTS,\n TemplateInclusion.DATA,\n\
\ TemplateInclusion.DISCUSSIONS }\n);\n\n"
- lang: Java
source: "// Sample 1: Create sheet in workspace\n// Specify properties of\
\ the first column\nColumn columnA = new Column()\n .setTitle(\"\
Favorite\")\n .setType(ColumnType.CHECKBOX)\n .setSymbol(Symbol.STAR);\n\
\n// Specify properties of the second column\nColumn columnB = new Column()\n\
\ .setTitle(\"Primary Column\")\n .setType(ColumnType.TEXT_NUMBER)\n\
\ .setPrimary(true);\n\n// Create sheet in workspace (specifying\
\ the 2 columns to include in the sheet)\nSheet newSheet = new Sheet();\n\
\ newSheet.setName(\"new sheet title\");\n newSheet.setColumns(Arrays.asList(columnA,\
\ columnB));\n\nsmartsheet.sheetResources().createSheetInWorkspace(\n \
\ 3734419270854532L, // long workspaceId\n newSheet\n \
\ );\n\n// Sample 2: Create sheet in workspace from template\n// Specify\
\ name for the sheet and Id of the template\nSheet sheet = new Sheet();\n\
sheet.setFromId(7679398137620356L); // long templateId\nsheet.setName(\"\
newsheet\");\n\n// Option 1: Omit 'include' parameter\nSheet newSheet =\
\ smartsheet.sheetResources().createSheetInWorkspaceFromTemplate(\n \
\ 1656220827314052L, // long workspaceId\n sheetSpecification,\n\
\ null // EnumSet\
\ includes\n );\n\n// Option 2: Include ATTACHMENTS, DATA, and DISCUSSIONS\n\
Sheet newSheet = smartsheet.sheetResources().createSheetInWorkspaceFromTemplate(\n\
\ 1656220827314052L, // long workspaceId\n \
\ sheetSpecification,\n EnumSet.of(\n SheetTemplateInclusion.ATTACHMENTS,\n\
\ SheetTemplateInclusion.DATA,\n SheetTemplateInclusion.DISCUSSIONS)\n\
\ );\n\n"
- lang: JavaScript
source: "// Sample 1: Create sheet in workspace\n// Specify sheet properties\n\
var sheet = {\n \"name\": \"newsheet\",\n \"columns\": [\n {\n \
\ \"title\": \"Favorite\",\n \"type\": \"CHECKBOX\",\n \"symbol\"\
: \"STAR\"\n },\n {\n \"title\": \"Primary Column\",\n \"\
primary\": true,\n \"type\": \"TEXT_NUMBER\"\n }\n ]\n};\n\n//\
\ Set options\nvar options = {\n workspaceId: 1656220827314052,\n body:\
\ sheet\n};\n\n// Create sheet in workspace\nsmartsheet.sheets.createSheetInWorkspace(options)\n\
\ .then(function(newSheet) {\n console.log(newSheet);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n\n// Sample 2: Create sheet in workspace\
\ from template\n// Specify the directive\nvar sheet = {\n \"fromId\":\
\ 7679398137620356,\n \"name\": \"newsheet\"\n };\n\n// Set options\n\
var options = {\n workspaceId: 1656220827314052,\n body: sheet\n };\n\
\n// Create sheet from template in the specified workspace\nsmartsheet.sheets.createSheetFromExisting(options)\n\
\ .then(function(newSheet) {\n console.log(newSheet);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n\n"
label: Node.js
- lang: Python
source: "# Sample 1: Create sheet in workspace\nsheet_spec = smartsheet.models.Sheet({\n\
\ 'name': 'newsheet',\n 'columns': [{\n 'title': 'Favorite',\n \
\ 'type': 'CHECKBOX',\n 'symbol': 'STAR'\n }, {\n 'title':\
\ 'Primary Column',\n 'primary': True,\n 'type': 'TEXT_NUMBER'\n\
\ }\n ]\n})\n\nresponse = smartsheet_client.Workspaces.create_sheet_in_workspace(\n\
\ 3734419270854532, # workspace_id\n sheet_spec)\nnew_sheet\
\ = response.result\n\n# Sample 2: Create sheet in workspace from template\n\
response = smartsheet_client.Workspaces.create_sheet_in_workspace_from_template(\n\
\ 1656220827314052, # workspace_id\n smartsheet.models.Sheet({\n\
\ 'name': 'newsheet',\n 'from_id': 7679398137620356 # template_id\n\
\ })\n)\n\n"
- lang: Ruby
source: "# Sample 1: Create sheet in workspace\nbody = {\n name: 'newsheet',\n\
\ columns: [\n {\n title: 'Favorite',\n type: 'CHECKBOX',\n\
\ symbol: 'STAR',\n width: 10\n },\n {\n title: 'Primary\
\ Column',\n type: 'TEXT_NUMBER',\n primary: true\n }\n ]\n\
}\n\nresponse = smartsheet.sheets.create_in_workspace(\n workspace_id:\
\ 3734419270854532,\n body: body\n)\nnew_sheet = response[:result]\n\n\
# Sample 2: Create sheet in workspace from template\nbody = {\n name: 'newsheet',\n\
\ from_id: 7679398137620356\n}\n\nresponse = smartsheet.sheets.create_in_workspace_from_template(\n\
\ workspace_id: 1656220827314052,\n body: body\n)\nnew_sheet = response[:result]\n\
\n"
/workspaces/{workspaceId}/sheets/import:
parameters:
- $ref: '#/paths/~1contacts/parameters/0'
- $ref: '#/paths/~1workspaces~1%7BworkspaceId%7D/parameters/1'
post:
summary: Import Sheet into Workspace
description: >
Imports CSV or XLSX data into a new sheet in the specified workspace.
Note the following:
* Both sheetName and the file name must use ASCII characters.
* The source data must be basic text. To include rich formula data, import
and create a sheet first, and then use Update Rows. To work with images, see
Cell Images.
* XLS is not supported. You must use XLSX.
* Hierarchical relationships between rows in an external file won't import.
operationId: import-sheet-into-workspace
tags:
- import
security:
- APIToken: []
- OAuth2:
- CREATE_SHEETS
parameters:
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/0'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/1'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/2'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/3'
- $ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/parameters/4'
requestBody:
description: Binary content for the CSV / XLSX file.
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: Result object containing a Sheet object for imported sheet.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1folders~1%7BfolderId%7D/delete/responses/200/content/application~1json/schema'
- type: object
properties:
result:
$ref: '#/paths/~1folders~1%7BfolderId%7D~1sheets~1import/post/responses/200/content/application~1json/schema/allOf/1/properties/result'
default:
description: Generic Error Payload
content:
application/json:
schema:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
x-codeSamples:
- lang: cURL
source: "curl https://api.smartsheet.com/2.0/workspaces/{workspaceId}/sheets/import?sheetName=MarketingProgressReport&headerRowIndex=0&primaryColumnIndex=0\
\ \\\n-H \"Authorization: Bearer ll352u9jujauoqz4gstvsae05\" \\\n-H \"Content-Disposition:\
\ attachment\" \\\n-H \"Content-Type: text/csv\" \\\n-X POST \\\n--data-binary\
\ @ProgressReport.csv\n"
- lang: C#
source: "Sheet sheet = smartsheet.WorkspaceResources.SheetResources.ImportXlsSheet(\n\
\ 4124946017347460, // workspaceId\n \"D:/ProgressReport.xlsx\"\
,\n null, // sheetName defaults to file name unless specified\n\
\ 0, // headerRowIndex\n null \
\ // primaryColumnIndex\n);\n"
- lang: Java
source: "Sheet sheet = smartsheet.sheetResources().importXlsxInWorkspace(\n\
\ 4124946017347460L, // long workspaceId\n \"D:/ProgressReport.xlsx\"\
,\n \"MarketingProgressReport\",\n 0, \
\ // headerRowIndex\n 0 // primaryColumnIndex\n\
\ );\n"
- lang: JavaScript
source: "// Sample 1: Import CSV into workspace\n// Set options\nvar options\
\ = {\n workspaceId: 4124946017347460,\n queryParameters: {\n sheetName:\
\ 'MarketingProgressReport'\n },\n path: \"D:/ProgressReport.csv\"\n};\n\
\n// Import CSV as sheet into workspace\nsmartsheet.sheets.importCsvSheetIntoWorkspace(options)\n\
\ .then(function(attachment) {\n console.log(attachment);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n\n// Sample 2: Import XLSX into workspace\n\
// Set options\nvar options = {\n workspaceId: 4124946017347460,\n queryParameters:\
\ {\n sheetName: 'MarketingProgressReport'\n },\n path: \"D:/ProgressReport.xlsx\"\
\n};\n\n// Import XLSX as sheet into workspace\nsmartsheet.sheets.importXlsxSheetIntoWorkspace(options)\n\
\ .then(function(attachment) {\n console.log(attachment);\n })\n .catch(function(error)\
\ {\n console.log(error);\n });\n"
label: Node.js
- lang: Python
source: "imported_sheet = smartsheet_client.Workspaces.import_xlsx_sheet(\n\
\ 4124946017347460, # workspace_id\n 'D:/ProgressReport.xlsx',\n\
\ 'MarketingProgressReport', # sheet_name\n header_row_index=0\n)\n"
- lang: Ruby
source: "# Sample 1: Import from file into workspace\nsmartsheet.sheets.import_from_file_into_workspace(\n\
\ workspace_id: 4124946017347460,\n file: sample_csv,\n file_type: :csv,\n\
\ file_length: sample_csv.size,\n params: {sheetName: 'MarketingProgressReport',\
\ headerRowIndex: 0, primaryColumnIndex: 0})\n\n# Sample 2: Import from\
\ file path into workspace\nsmartsheet.sheets.import_from_file_path_into_workspace(\n\
\ workspace_id: 4124946017347460,\n path: 'D:\\sample.csv',\n file_type:\
\ :csv,\n params: {sheetName: 'MarketingProgressReport', headerRowIndex:\
\ 0, primaryColumnIndex: 0})\n"
components:
schemas:
AccessLevel:
type: string
enum:
- ADMIN
- EDITOR
- EDITOR_SHARE
- OWNER
- VIEWER
Account:
type: object
properties:
id:
description: Account Id.
type: number
example: 122454719915908
name:
description: Account name.
type: string
example: Smartsheet Org
AlternateEmail:
type: object
properties:
id:
description: AlternateEmail Id.
type: number
example: 8150532427671428
confirmed:
description: Indicates whether the alternate email address has been confirmed.
type: boolean
example: true
email:
description: User's alternate email address.
type: string
example: johnathan.doe@smartsheet.com
Attachment:
description: Attachment Object
type: object
properties:
id:
description: Attachment Id.
type: number
parentId:
description: The Id of the parent.
type: number
attachmentType:
description: Attachment type. * types are not supported for Smartsheet.gov
accounts.
type: string
enum:
- BOX_COM
- DROPBOX*
- EGNYTE*
- EVERNOTE*
- FILE
- GOOGLE_DRIVE
- LINK
- ONEDRIVE
attachmentSubType:
description: Attachment sub type. * type is for EGNYTE values and the rest
are GOOGLE_DRIVE values.
type: string
enum:
- DOCUMENT
- DRAWING
- FOLDER*
- PDF
- PRESENTATION
- SPREADSHEET
mimeType:
description: Attachment MIME type.
type: string
example: PNG
parentType:
description: The type of object the attachment belongs to.
type: string
enum:
- COMMENT
- PROOF
- ROW
- SHEET
createdAt:
oneOf:
- type: string
format: date-time
- type: number
readOnly: true
createdBy:
description: >
`User` object containing `name` and `email` of the user who created
this attachment.
allOf:
- description: MiniUser Object
type: object
properties:
email:
type: string
format: email
example: jane.doe@smartsheet.com
name:
type: string
readOnly: true
example: Jane Doe
name:
description: Attachment name.
type: string
sizeInKb:
description: The size of the file, if the attachmentType is FILE.
type: number
url:
description: Attachment temporary URL (files only).
type: string
urlExpiresInMillis:
description: Attachment temporary URL time to live (files only).
type: number
AutomationAction:
type: object
properties:
includedColumnIds:
description: Specifies which columns to include in message.
type: array
items:
type: number
type:
type: string
enum:
- APPROVAL_REQUEST_ACTION
- NOTIFICATION_ACTION
- UPDATE_REQUEST_ACTION
frequency:
type: string
enum:
- DAILY
- HOURLY
- IMMEDIATELY
- WEEKLY
includeAllColumns:
description: If true, all columns are included in email contents.
type: boolean
default: true
includeAttachments:
description: If true, all attachments are included in email contents.
type: string
includeDiscussions:
description: If true, all discussions are included in email contents.
type: boolean
message:
description: Email body.
type: string
subject:
description: Email subject line.
type: string
oneOf:
- properties:
notifyAllSharedUsers:
description: If true, notifications are sent to all users shared to the
sheet.
type: boolean
- properties:
recipients:
type: array
items:
description: >
Specifies the recipient of an email. The recipient may be
either an individual or a group. To specify an individual, set
the email attribute; to specify a group, set the groupId
attribute. Either email and groupId may be set, but not both.
oneOf:
- type: object
description: >
Specifies the recipient of an [Email]($ref:
'Email.yaml#/components/schemas/Email'). The recipient may
be either an individual or a group. To specify an
individual, set the **email** attribute; to specify a
group, set the **groupId** attribute. Either **email** and
**groupId** may be set, but not both.
properties:
email:
description: The email address of an individual recipient.
type: string
format: email
example: john.doe@smartsheet.com
- type: object
description: >
Specifies the recipient of an [Email]($ref:
'Email.yaml#/components/schemas/Email'). The recipient may
be either an individual or a group. To specify an
individual, set the **email** attribute; to specify a
group, set the **groupId** attribute. Either **email** and
**groupId** may be set, but not both.
properties:
groupId:
description: The Id of a group recipient.
type: number
example: 2258118617917316
- properties:
recipientColumnIds:
description: Array of column Ids from which to collect email recipients.
type: array
items:
type: number
AutomationRule:
type: object
properties:
id:
description: AutomationRule Id.
type: number
action:
description: AutomationAction object containing information for this rule,
such as type, recipients, and frequency.
allOf:
- type: object
properties:
includedColumnIds:
description: Specifies which columns to include in message.
type: array
items:
type: number
type:
type: string
enum:
- APPROVAL_REQUEST_ACTION
- NOTIFICATION_ACTION
- UPDATE_REQUEST_ACTION
frequency:
type: string
enum:
- DAILY
- HOURLY
- IMMEDIATELY
- WEEKLY
includeAllColumns:
description: If true, all columns are included in email contents.
type: boolean
default: true
includeAttachments:
description: If true, all attachments are included in email contents.
type: string
includeDiscussions:
description: If true, all discussions are included in email contents.
type: boolean
message:
description: Email body.
type: string
subject:
description: Email subject line.
type: string
oneOf:
- properties:
notifyAllSharedUsers:
description: If true, notifications are sent to all users shared
to the sheet.
type: boolean
- properties:
recipients:
type: array
items:
$ref: '#/components/schemas/AutomationAction/oneOf/1/properties/recipients/items'
- properties:
recipientColumnIds:
description: Array of column Ids from which to collect email recipients.
type: array
items:
type: number
createdAt:
description: A timestamp of when the rule was originally added.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: >
`User` object containing `name` and `email` of the creator of this
rule.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
disabledReason:
description: >
Machine-readable reason a rule is disabled:
* `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.
type: string
enum:
- APPROVAL_COLUMN_MISSING
- APPROVAL_COLUMN_WRONG_TYPE
- AUTOMATION_NOT_ENABLED_FOR_ORG
- COLUMN_MISSING
- COLUMN_TYPE_INCOMPATIBLE
- NO_POTENTIAL_RECIPIENTS
- NO_VALID_SELECTED_COLUMNS
disabledReasonText:
description: Descriptive reason a rule is disabled.
type: string
enabled:
description: If true, indicates that the rule is active.
type: boolean
modifiedAt:
description: The datetime for when the change was made to the rule.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedBy:
description: >
`User` object containing the `name` and `email` of the user that
made the change.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
name:
description: Rule name as shown in the UI.
type: string
userCanModify:
description: If true, indicates that the current user can modify the rule.
type: boolean
AutoNumberFormat:
type: object
description: Object that describes how the the System Column type of "AUTO_NUMBER"
is auto-generated.
properties:
fill:
description: Indicates zero-padding. Must be between 0 and 10 "0" (zero)
characters.
type: string
prefix:
description: |
The prefix. Can include the date tokens:
* {DD}
* {MM}
* {YY}
* {YYYY}
type: string
startingNumber:
description: The starting number for the auto-id.
type: number
suffix:
description: |
The suffix. Can include the date tokens:
* {DD}
* {MM}
* {YY}
* {YYYY}
type: string
BulkItemFailure:
type: object
properties:
rowId:
description: The Id of the row that failed. Applicable only to bulk row
operations.
type: number
nullable: true
error:
description: The error caused by the failed item.
type: object
properties:
refId:
description: The Id of the specific error occurrence. Please include
this information when contacting Smartsheet support.
type: string
errorCode:
description: Custom error code from Smartsheet. See the complete [Error
Code List](../#section/Error-Code-List).
type: number
message:
description: Descriptive error message.
type: string
index:
description: The index of the failed item in the bulk request array.
type: number
Callback:
type: object
properties:
scopeObjectId:
type: number
description: Id of the object that corresponds to scope.
example: 3285357287499652
readOnly: true
webhookId:
type: number
description: Id of the corresponding webhook.
example: 8444254503626628
events:
description: Array of CallbackEvent objects
type: array
items:
type: object
properties:
id:
type: number
description: Id of the object that corresponds to objectType. Omitted
if objectType is cell.
example: 3285357287499652
columnId:
type: number
description: Only present if objectType is cell. The Id of the column
where the cell is located.
nullable: true
rowid:
type: number
description: Only present if objectType is cell. The Id of the row
where the cell is located.
nullable: true
userid:
type: number
description: The user Id of the person who caused this event.
example: 48569348493401210
objectType:
description: Type of object for which event occurred.
type: string
enum:
- attachment
- cell
- column
- comment
- discussion
- row
- sheet
example: sheet
changeAgent:
type: string
description: A comma-delimited list of values that uniquely identify
the agents responsible for making the changes that caused the callback
to occur. Only present if the change agent included the Smartsheet-Change-Agent
header in the API request that changed data in Smartsheet. For more
information, see [Preventing Infinite Loops](../../tag/webhooksDescription#section/Preventing-Infinite-Loops).
eventType:
type: string
description: Type of Event that occurred.
enum:
- created
- deleted
- updated
example: created
timestamp:
type: string
format: date-time
description: Time that this event occurred. A callback may contain
events with different timestamps, as multiple separate events may
be aggregated into a single callback request.
newWebhookStatus:
type: string
description: New status of the corresponding webhook. Only returned for
webhook status change callbacks (null for event callbacks).
example: ENABLED
nonce:
type: string
description: Random value that is distinct for each callback.
scope:
type: string
description: Scope of the webhook. Currently, the only supported value is
sheet.
enum:
- sheet
example: sheet
timestamp:
type: string
format: date-time
description: Time that the callback was generated.
CallbackEvent:
type: object
properties:
id:
type: number
description: Id of the object that corresponds to objectType. Omitted if
objectType is cell.
example: 3285357287499652
columnId:
type: number
description: Only present if objectType is cell. The Id of the column where
the cell is located.
nullable: true
rowid:
type: number
description: Only present if objectType is cell. The Id of the row where
the cell is located.
nullable: true
userid:
type: number
description: The user Id of the person who caused this event.
example: 48569348493401210
objectType:
description: Type of object for which event occurred.
type: string
enum:
- attachment
- cell
- column
- comment
- discussion
- row
- sheet
example: sheet
changeAgent:
type: string
description: A comma-delimited list of values that uniquely identify the
agents responsible for making the changes that caused the callback to
occur. Only present if the change agent included the Smartsheet-Change-Agent
header in the API request that changed data in Smartsheet. For more information,
see [Preventing Infinite Loops](../../tag/webhooksDescription#section/Preventing-Infinite-Loops).
eventType:
type: string
description: Type of Event that occurred.
enum:
- created
- deleted
- updated
example: created
timestamp:
type: string
format: date-time
description: Time that this event occurred. A callback may contain events
with different timestamps, as multiple separate events may be aggregated
into a single callback request.
Cell:
type: object
properties:
columnId:
type: number
description: The Id of the column that the cell is located in.
columnType:
type: string
description: Only returned if the include query string parameter contains
**columnType**.
conditionalFormat:
type: string
description: 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:
type: string
description: Visual representation of cell contents, as presented to the
user in the UI.
format:
type: string
description: The format descriptor. Only returned if the include query string
parameter contains **format** and this cell has a non-default format applied.
formula:
type: string
description: 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"**.
hyperlink:
type: object
properties:
reportId:
type: number
description: If non-null, this hyperlink is a link to the report with
this Id.
sheetId:
type: number
description: If non-null, this hyperlink is a link to the sheet with
this Id.
sightId:
type: number
description: If non-null, this hyperlink is a link to the dashboard
with this Id.
url:
type: string
description: 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.
image:
type: object
properties:
altText:
type: string
description: Alternate text for the image.
height:
type: number
description: Original height (in pixels) of the uploaded image.
id:
type: string
description: Image Id.
width:
type: number
description: Original width (in pixels) of the uploaded image.
linkInFromCell:
type: object
properties:
columnId:
type: number
description: Column Id of the linked cell.
rowId:
type: number
description: Row Id of the linked cell.
sheetId:
type: number
description: Sheet Id of the sheet that the linked cell belongs to.
sheetName:
type: string
description: Sheet name of the linked cell.
status:
type: string
enum:
- BLOCKED
- BROKEN
- CIRCULAR
- DISABLED
- INACCESSIBLE
- INVALID
- NOT_SHARED
- OK
description: >
* `BLOCKED` One of several other values indicating unusual error
conditions.
* `BROKEN` The row or sheet linked to was deleted.
* `CIRCULAR` One of several other values indicating unusual error
conditions.
* `DISABLED` One of several other values indicating unusual error
conditions.
* `INACCESSIBLE` The sheet linked to cannot be viewed by this user.
* `INVALID` One of several other values indicating unusual error conditions.
* `NOT_SHARED` One of several other values indicating unusual error
conditions.
* `OK` The link is in a good state.
linksOutToCells:
type: array
items:
$ref: '#/components/schemas/Cell/properties/linkInFromCell'
objectValue:
description: 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.
type: object
properties:
objectType:
type: string
enum:
- ABSTRACT_DATETIME
- CONTACT
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT
- MULTI_PICKLIST
- PREDECESSOR_LIST
overrideValidation:
type: boolean
description: (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:
type: boolean
description: 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.
value:
anyOf:
- type: string
- type: number
- type: boolean
description: 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.
CellDataItem:
type: object
properties:
columnId:
description: Column Id for each item.
type: number
rowId:
description: Row Id for each item.
type: number
sheetId:
description: Sheet Id for each item.
type: number
objectValue:
description: The type of data returned depends on the cell type and the
data in the cell.
oneOf:
- type: boolean
- type: number
- type: string
cell:
type: object
properties:
columnId:
type: number
description: The Id of the column that the cell is located in.
columnType:
type: string
description: Only returned if the include query string parameter contains
**columnType**.
conditionalFormat:
type: string
description: 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:
type: string
description: Visual representation of cell contents, as presented to
the user in the UI.
format:
type: string
description: The format descriptor. Only returned if the include query
string parameter contains **format** and this cell has a non-default
format applied.
formula:
type: string
description: 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"**.
hyperlink:
$ref: '#/components/schemas/Cell/properties/hyperlink'
image:
$ref: '#/components/schemas/Cell/properties/image'
linkInFromCell:
$ref: '#/components/schemas/Cell/properties/linkInFromCell'
linksOutToCells:
type: array
items:
$ref: '#/components/schemas/Cell/properties/linkInFromCell'
objectValue:
$ref: '#/components/schemas/Cell/properties/objectValue'
overrideValidation:
type: boolean
description: (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:
type: boolean
description: 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.
value:
anyOf:
- type: string
- type: number
- type: boolean
description: 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.
dataSource:
type: string
enum:
- CELL
- SUMMARY_FIELD
inheritCellValue:
description: Specifies if valueFormat is inherited from the underlying cell
value
type: boolean
label:
description: Label for the data point. This is either the column name or
a user-provided string.
type: string
labelFormat:
description: Format description for label.
type: string
example: ',,1,1,,,,,,,,,,,,,'
order:
description: The display order for the CellDataItem.
type: number
profileField:
type: object
properties:
id:
description: SummaryField Id.
type: number
contactOptions:
description: Array of ContactOption objects to specify a pre-defined
list of values for the column. Column type must be CONTACT_LIST.
type: array
items:
$ref: '#/components/schemas/Column/properties/contactOptions/items'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: User object containing name and email of the creator of
this summary field.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
displayValue:
description: Visual representation of cell contents, as presented to
the user in the UI.
type: string
format:
description: The format descriptor. Only returned if the include query
string parameter contains format and this column has a non-default
format applied to it.
type: string
formula:
description: The formula for a cell, if set.
type: string
hyperlink:
$ref: '#/components/schemas/Cell/properties/hyperlink'
image:
$ref: '#/components/schemas/Cell/properties/image'
index:
description: Field index or position. This number is zero-based.
type: number
locked:
description: Indicates whether the field is locked.
type: boolean
lockedForUser:
description: Indicates whether the field is locked for the requesting
user.
type: boolean
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedBy:
description: User object containing name and email of the user who most
recently modified this summary field.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
objectValue:
$ref: '#/components/schemas/Cell/properties/objectValue'
options:
description: When applicable for PICKLIST column type. Array of the
options available for the field.
type: array
items:
type: string
symbol:
description: When applicable for PICKLIST column type.
type: string
title:
description: Arbitrary name, must be unique within summary.
type: string
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
validation:
description: Indicates whether summary field values are restricted to
the type.
type: boolean
valueFormat:
description: Format description for value.
type: string
example: ',,1,1,,,,,,,,,,,,,'
CellHistory:
type: object
allOf:
- $ref: '#/components/schemas/CellDataItem/properties/cell'
properties:
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedBy:
description: User object containing the name and email of the user that
made the change.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
CellLink:
type: object
properties:
columnId:
type: number
description: Column Id of the linked cell.
rowId:
type: number
description: Row Id of the linked cell.
sheetId:
type: number
description: Sheet Id of the sheet that the linked cell belongs to.
sheetName:
type: string
description: Sheet name of the linked cell.
status:
type: string
enum:
- BLOCKED
- BROKEN
- CIRCULAR
- DISABLED
- INACCESSIBLE
- INVALID
- NOT_SHARED
- OK
description: >
* `BLOCKED` One of several other values indicating unusual error
conditions.
* `BROKEN` The row or sheet linked to was deleted.
* `CIRCULAR` One of several other values indicating unusual error conditions.
* `DISABLED` One of several other values indicating unusual error conditions.
* `INACCESSIBLE` The sheet linked to cannot be viewed by this user.
* `INVALID` One of several other values indicating unusual error conditions.
* `NOT_SHARED` One of several other values indicating unusual error conditions.
* `OK` The link is in a good state.
CellLinkWidgetContent:
type: object
title: Metric
properties:
type:
type: string
enum:
- METRIC
- SHEETSUMMARY
sheetId:
description: Sheet Id from which the cell data originates.
type: number
cellData:
type: array
items:
type: object
properties:
columnId:
description: Column Id for each item.
type: number
rowId:
description: Row Id for each item.
type: number
sheetId:
description: Sheet Id for each item.
type: number
objectValue:
description: The type of data returned depends on the cell type and
the data in the cell.
oneOf:
- type: boolean
- type: number
- type: string
cell:
$ref: '#/components/schemas/CellDataItem/properties/cell'
dataSource:
type: string
enum:
- CELL
- SUMMARY_FIELD
inheritCellValue:
description: Specifies if valueFormat is inherited from the underlying
cell value
type: boolean
label:
description: Label for the data point. This is either the column name
or a user-provided string.
type: string
labelFormat:
description: Format description for label.
type: string
example: ',,1,1,,,,,,,,,,,,,'
order:
description: The display order for the CellDataItem.
type: number
profileField:
$ref: '#/components/schemas/CellDataItem/properties/profileField'
valueFormat:
description: Format description for value.
type: string
example: ',,1,1,,,,,,,,,,,,,'
columns:
type: array
items:
type: object
properties:
autoNumberFormat:
$ref: '#/components/schemas/Column/properties/autoNumberFormat'
contactOptions:
type: array
items:
$ref: '#/components/schemas/Column/properties/contactOptions/items'
description: Array of ContactOption objects to specify a pre-defined
list of values for the column. Column **type** must be **CONTACT_LIST**.
description:
type: string
description: Column description.
format:
type: string
description: The format descriptor (see [Formatting](../../#section/API-Basics/Formatting)).
Only returned if the **include** query string parameter contains
**format** and this column has a non-default format applied to it.
hidden:
type: boolean
description: Indicates whether the column is hidden.
id:
type: number
description: Column Id.
index:
type: number
description: Column index or position. This number is zero-based.
locked:
type: boolean
description: 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:
type: boolean
description: 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:
type: array
items:
type: string
description: Array of the options available for the column.
primary:
type: boolean
description: Returned only if the column is the Primary Column (value
= **true**).
symbol:
type: string
description: When applicable for **CHECKBOX** or **PICKLIST** column
types. See [Symbol Columns](../../tag/columnsRelated#section/Column-Types/Symbol-Columns).
systemColumnType:
type: string
enum:
- AUTO_NUMBER
- CREATED_BY
- CREATED_DATE
- MODIFIED_BY
- MODIFIED_DATE
description: See [System Columns](../../tag/columnsRelated#section/Column-Types).
tags:
type: array
items:
type: string
enum:
- CALENDAR_END_DATE
- CALENDAR_START_DATE
- CARD_DONE
- GANTT_ALLOCATION
- GANTT_ASSIGNED_RESOURCE
- GANTT_DISPLAY_LABEL
- GANTT_DURATION
- GANTT_END_DATE
- GANTT_PERCENT_COMPLETE
- GANTT_PREDECESSOR
- GANTT_START_DATE
- BASELINE_START_DATE
- BASELINE_END_DATE
- BASELINE_VARIANCE
description: Set of tags to indicate special columns. Each element
in the array is set to one of the listed enum values.
title:
type: string
description: Column title.
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
description: See [Column Types](../../tag/columnsRelated#section/Column-Types)
validation:
type: boolean
description: Indicates whether validation has been enabled for the
column (value = **true**).
version:
type: number
enum:
- 0
- 1
- 2
description: |
* `0`: CONTACT_LIST, PICKLIST, or TEXT_NUMBER.
* `1`: MULTI_CONTACT_LIST.
* `2`: MULTI_PICKLIST.
width:
type: number
description: Display width of the column in pixels.
hyperlink:
type: object
properties:
interactionType:
description: >
Specifies what happens when a user clicks the widget. The type
will determine what other properties are needed.
* DISTI_COPY - a distribution link, only available if org has distribution
links enabled.
* NONE - do nothing, no other attribute required.
* SMARTSHEET_ITEM - open a Smartsheet item that is not the SOURCE_SHEET,
must also have one of the following attributes:
* dashboardId
* folderId
* reportId
* sheetId
* workspaceId
* SOURCE_SHEET - open the container where the widget data comes from,
no other attribute required.
* WEB - launch the URL, must also have url attribute.
type: string
enum:
- DISTI_COPY
- NONE
- SMARTSHEET_ITEM
- SOURCE_SHEET
- WEB
folderId:
description: If interactionType = SMARTSHEET_ITEM this is the folder
to open.
type: number
reportId:
description: If interactionType = SMARTSHEET_ITEM this is the report
to open.
type: number
sheetId:
description: If interactionType = SMARTSHEET_ITEM this is the sheet
to open.
type: number
sightId:
description: If interactionType = SMARTSHEET_ITEM this is the dashboard
to open.
type: number
url:
description: If interactionType = WEB this is the URL to launch.
type: string
workspaceId:
description: If interactionType = SMARTSHEET_ITEM this is the workspace
to open.
type: number
ChartWidgetContent:
type: object
title: Chart
properties:
type:
type: string
enum:
- CHART
reportId:
description: Report Id denoting container source, if applicable.
type: number
sheetId:
description: Sheet Id denoting container source, if applicable.
type: number
axes:
type: array
items:
type: object
properties:
location:
description: Describes location of the axis.
type: string
enum:
- BOTTOM
- LEFT
- NONE
- RIGHT
- TOP
title:
description: Axis title.
type: string
titleInfo:
type: object
properties:
type:
type: string
enum:
- ABSTRACT_DATE_TIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATE_TIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
axisLabelFormat:
description: Describes the axis format (see [Formatting](/section/Formatting)).
type: string
example: ',,,,,,,,36,,,,,,,,'
includeZero:
description: Includes 0 in the axis.
type: boolean
hyperlink:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/hyperlink'
includedColumnIds:
description: Array of column Ids if the range was selected through the UI.
type: array
items:
type: number
legend:
type: object
properties:
location:
type: string
enum:
- BOTTOM
- LEFT
- NONE
- RIGHT
- TOP
legendFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the legend has a non-default format applied to it.
example: ',,1,1,,,,,,,,,,,,,'
selectionRanges:
type: array
items:
description: Defines a block of cells in a sheet.
type: object
properties:
sourceColumnId1:
description: Defines beginning edge of range when specifying one or
more columns.
type: number
sourceColumnId2:
description: Defines ending edge of range when specifying one or more
columns.
type: number
sourceRowId1:
description: Defines beginning edge of range when specifying one or
more rows.
type: number
sourceRowId2:
description: Defines ending edge of range when specifying one or more
rows.
type: number
series:
type: array
items:
type: object
properties:
title:
type: string
titleInfo:
$ref: '#/components/schemas/ChartWidgetContent/properties/axes/items/properties/titleInfo'
seriesTitleFormat:
type: string
description: Series title format (see [Formatting](/section/Formatting)).
seriesType:
type: string
enum:
- AREA
- BAR
- COLUMN
- LINE
- PIE
- SCATTER
dataLabels:
type: object
properties:
labelType:
type: string
enum:
- NONE
- PERCENT
- VALUE
tooltips:
type: object
properties:
labelType:
type: string
enum:
- NONE
- PERCENT
- X_SERIES_Y
- X_Y_PERCENT
- Y
- Y_PERCENT
lineType:
type: string
enum:
- CURVED
- STEPPED
- STRAIGHT
holeSize:
type: number
isFilled:
type: boolean
isHalf:
type: boolean
isStacked:
type: boolean
xFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the series has a non-default format applied to
it.
example: ',,1,1,,,,,,,,,,,,,'
yFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the series has a non-default format applied to
it.
example: ',,1,1,,,,,,,,,,,,,'
color:
type: string
axisLocationX:
type: string
enum:
- BOTTOM
- LEFT
- NONE
- RIGHT
- TOP
axisLocationY:
type: string
enum:
- BOTTOM
- LEFT
- NONE
- RIGHT
- TOP
yColumnInfo:
$ref: '#/components/schemas/ChartWidgetContent/properties/axes/items/properties/titleInfo'
xColumnInfo:
$ref: '#/components/schemas/ChartWidgetContent/properties/axes/items/properties/titleInfo'
seriesSelectionOrder:
type: string
enum:
- COLUMNS
- ROWS
seriesData:
type: array
items:
type: object
properties:
x:
type: number
y:
type: number
xFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the series has a non-default format applied
to it.
example: ',,1,1,,,,,,,,,,,,,'
yFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the series has a non-default format applied
to it.
example: ',,1,1,,,,,,,,,,,,,'
color:
type: string
selectionRanges:
type: array
items:
$ref: '#/components/schemas/ChartWidgetContent/properties/selectionRanges/items'
verticalGridLines:
type: object
properties:
lineStyle:
type: string
enum:
- SOLID
horizontalGridLines:
$ref: '#/components/schemas/ChartWidgetContent/properties/verticalGridLines'
Column:
type: object
properties:
autoNumberFormat:
type: object
description: Object that describes how the the System Column type of "AUTO_NUMBER"
is auto-generated.
properties:
fill:
description: Indicates zero-padding. Must be between 0 and 10 "0" (zero)
characters.
type: string
prefix:
description: |
The prefix. Can include the date tokens:
* {DD}
* {MM}
* {YY}
* {YYYY}
type: string
startingNumber:
description: The starting number for the auto-id.
type: number
suffix:
description: |
The suffix. Can include the date tokens:
* {DD}
* {MM}
* {YY}
* {YYYY}
type: string
contactOptions:
type: array
items:
type: object
properties:
email:
description: A parsable email address.
type: string
name:
description: Can be a user's name, display name, or free text.
type: string
description: Array of ContactOption objects to specify a pre-defined list
of values for the column. Column **type** must be **CONTACT_LIST**.
description:
type: string
description: Column description.
format:
type: string
description: The format descriptor (see [Formatting](../../#section/API-Basics/Formatting)).
Only returned if the **include** query string parameter contains **format**
and this column has a non-default format applied to it.
hidden:
type: boolean
description: Indicates whether the column is hidden.
id:
type: number
description: Column Id.
index:
type: number
description: Column index or position. This number is zero-based.
locked:
type: boolean
description: 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:
type: boolean
description: 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:
type: array
items:
type: string
description: Array of the options available for the column.
primary:
type: boolean
description: Returned only if the column is the Primary Column (value =
**true**).
symbol:
type: string
description: When applicable for **CHECKBOX** or **PICKLIST** column types.
See [Symbol Columns](../../tag/columnsRelated#section/Column-Types/Symbol-Columns).
systemColumnType:
type: string
enum:
- AUTO_NUMBER
- CREATED_BY
- CREATED_DATE
- MODIFIED_BY
- MODIFIED_DATE
description: See [System Columns](../../tag/columnsRelated#section/Column-Types).
tags:
type: array
items:
type: string
enum:
- CALENDAR_END_DATE
- CALENDAR_START_DATE
- CARD_DONE
- GANTT_ALLOCATION
- GANTT_ASSIGNED_RESOURCE
- GANTT_DISPLAY_LABEL
- GANTT_DURATION
- GANTT_END_DATE
- GANTT_PERCENT_COMPLETE
- GANTT_PREDECESSOR
- GANTT_START_DATE
- BASELINE_START_DATE
- BASELINE_END_DATE
- BASELINE_VARIANCE
description: Set of tags to indicate special columns. Each element in the
array is set to one of the listed enum values.
title:
type: string
description: Column title.
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
description: See [Column Types](../../tag/columnsRelated#section/Column-Types)
validation:
type: boolean
description: Indicates whether validation has been enabled for the column
(value = **true**).
version:
type: number
enum:
- 0
- 1
- 2
description: |
* `0`: CONTACT_LIST, PICKLIST, or TEXT_NUMBER.
* `1`: MULTI_CONTACT_LIST.
* `2`: MULTI_PICKLIST.
width:
type: number
description: Display width of the column in pixels.
ColumnObject:
type: object
properties:
title:
type: string
description: Column title.
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
formula:
type: string
description: The formula for a column, if set, for instance **=data@row**.
hidden:
type: boolean
description: Indicates whether the column is hidden.
index:
type: number
description: Column index or position. This number is zero-based.
autoNumberFormat:
$ref: '#/components/schemas/Column/properties/autoNumberFormat'
contactOptions:
$ref: '#/components/schemas/Column/properties/contactOptions/items'
description:
type: string
description: Column description.
format:
type: string
description: The format descriptor (see [Formatting](../#section/API-Basics/Formatting)).
Only returned if the **include** query string parameter contains **format**
and this column has a non-default format applied to it.
locked:
type: boolean
description: 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:
type: boolean
description: 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:
type: array
items:
type: string
description: Array of the options available for the column.
symbol:
type: string
description: When applicable for **CHECKBOX** or **PICKLIST** column types.
See [Symbol Columns](../../tag/columnsRelated#section/Column-Types/Symbol-Columns).
systemColumnType:
type: string
enum:
- AUTO_NUMBER
- CREATED_BY
- CREATED_DATE
- MODIFIED_BY
- MODIFIED_DATE
description: See [System Columns](../../tag/columnsRelated#section/Column-Types)
validation:
type: boolean
description: Indicates whether validation has been enabled for the column
(value = **true**)
version:
type: number
description: >
Read only. The level of the column type. Each element in the array
is set to one of the following values:
* **0**: TEXT_NUMBER, CONTACT_LIST, or PICKLIST
* **1**: MULTI_CONTACT_LIST
* **2**: MULTI_PICKLIST
See [Versioning and Changes](#section/API-Basics/Versioning-and-Changes).
width:
type: number
description: Display width of the column in pixels.
Comment:
type: object
properties:
attachments:
description: Array of attachments on comments.
type: array
items:
description: Attachment Object
type: object
properties:
id:
description: Attachment Id.
type: number
parentId:
description: The Id of the parent.
type: number
attachmentType:
description: Attachment type. * types are not supported for Smartsheet.gov
accounts.
type: string
enum:
- BOX_COM
- DROPBOX*
- EGNYTE*
- EVERNOTE*
- FILE
- GOOGLE_DRIVE
- LINK
- ONEDRIVE
attachmentSubType:
description: Attachment sub type. * type is for EGNYTE values and
the rest are GOOGLE_DRIVE values.
type: string
enum:
- DOCUMENT
- DRAWING
- FOLDER*
- PDF
- PRESENTATION
- SPREADSHEET
mimeType:
description: Attachment MIME type.
type: string
example: PNG
parentType:
description: The type of object the attachment belongs to.
type: string
enum:
- COMMENT
- PROOF
- ROW
- SHEET
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: >
`User` object containing `name` and `email` of the user who
created this attachment.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
name:
description: Attachment name.
type: string
sizeInKb:
description: The size of the file, if the attachmentType is FILE.
type: number
url:
description: Attachment temporary URL (files only).
type: string
urlExpiresInMillis:
description: Attachment temporary URL time to live (files only).
type: number
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: User object containing name and email of the creator of this
comment.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
discussionId:
description: Discussion Id of discussion that contains comment.
type: number
id:
description: Comment Id.
type: number
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
text:
description: Comment body.
type: string
Contact:
type: object
properties:
id:
description: Contact Id.
type: string
example: AAAAATYU54QAD7_fNhTnhA
name:
description: Contact's full name.
type: string
example: Jane Doe
email:
description: Contact's email address.
type: string
format: email
example: jane.doe@smartsheet.com
ContactOption:
type: object
properties:
email:
description: A parsable email address.
type: string
name:
description: Can be a user's name, display name, or free text.
type: string
ContainerDestination:
type: object
properties:
destinationId:
description: The Id of the destination container (when copying or moving
a sheet or a folder). Required if destinationType is "folder" or "workspace".
If destinationType is "home", this value must be null.
type: number
destinationType:
description: Type of the destination container.
type: string
nullable: true
enum:
- folder
- home
- workspace
newName:
description: Name of the newly created object (when creating a copy of a
dashboard, folder, sheet, or workspace). This attribute is not supported
for "move" operations.
type: string
CopyOrMoveRowDestination:
type: object
properties:
sheetId:
description: The Id of the destination sheet.
type: number
CopyOrMoveRowDirective:
type: object
properties:
rowIds:
description: The Ids of the rows to move or copy from the source sheet.
type: array
items:
type: number
to:
type: object
properties:
sheetId:
description: The Id of the destination sheet.
type: number
CopyOrMoveRowResult:
type: object
properties:
destinationSheetId:
description: The Id of the destination sheet.
type: number
rowMappings:
description: Array of rowMapping objects.
type: array
items:
type: object
properties:
from:
description: Row Id in the source sheet.
type: number
to:
description: Row Id in the destination sheet.
type: number
Criteria:
type: object
properties:
columnId:
description: Column Id.
type: number
example: 293452983475
operator:
description: Operator used to filter column values.
type: string
enum:
- BETWEEN
- CONTAINS
- EQUAL
- FUTURE
- GREATER_THAN
- IS_BLANK
- IS_CHECKED
- IS_DATE
- IS_NUMBER
- IS_NOT_BLANK
- IS_NOT_CHECKED
- IS_NOT_DATE
- IS_NOT_NUMBER
- LAST_N_DAYS
- LESS_THAN
- NEXT_N_DAYS
- NOT_EQUAL
- PAST
- TODAY
example: IS_ONE_OF
values:
description: Present if a custom filter criteria's operator has one or more
arguments.
type: array
items:
type: string
example:
- Complete
- In progress
CrossSheetReference:
type: object
properties:
endColumnId:
description: Defines ending edge of range when specifying one or more columns.
To specify an entire column, omit the startRowId and endRowId parameters.
type: number
endRowId:
description: Defines ending edge of range when specifying one or more rows.
To specify an entire row, omit the startColumnId and endColumnId parameters.
type: number
id:
description: Cross-sheet reference Id, guaranteed unique within referencing
sheet.
type: number
name:
description: Friendly name of reference. Auto-generated unless specified
in Create Cross-sheet References.
type: string
startColumnId:
description: Defines beginning edge of range when specifying one or more
columns. To specify an entire column, omit the startRowId and endRowId
parameters.
type: number
startRowId:
description: Defines beginning edge of range when specifying one or more
rows. To specify an entire row, omit the startColumnId and endColumnId
parameters.
type: number
status:
description: >
Status of request:
* 'BLOCKED' - A reference is downstream of a circular issue.
* 'BROKEN' - The data source location (column, row or sheet) was deleted.
* 'CIRCULAR' - The formula reference is self referencing and cannot be
resolved.
* 'DISABLED' - Updating the reference is temporarily disabled due to
maintenance.
* 'INVALID/UNKNOWN' - The reference is new and had not been validated.
* 'NOT_SHARED' - No common shared users.
* 'OK' - The reference is in a good state.
type: string
enum:
- BLOCKED
- BROKEN
- CIRCULAR
- DISABLED
- INVALID/UNKNOWN
- NOT-SHARED
- OK
sourceSheetId:
description: Sheet Id of source sheet.
type: number
Currency:
type: object
properties:
code:
description: The ISO 4217 currency code.
example: EUR
type: string
symbol:
description: The currency symbol.
type: string
example: €
Discussion:
type: object
properties:
accessLevel:
type: string
enum:
- ADMIN
- EDITOR
- EDITOR_SHARE
- OWNER
- VIEWER
id:
description: Discussion Id.
type: number
comments:
description: Array of comments in discussion. Only returned if the include
query string parameter contains comments.
type: array
items:
type: object
properties:
attachments:
description: Array of attachments on comments.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: User object containing name and email of the creator
of this comment.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
discussionId:
description: Discussion Id of discussion that contains comment.
type: number
id:
description: Comment Id.
type: number
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
text:
description: Comment body.
type: string
commentAttachments:
description: Array of attachments on discussion comments. Only returned
if the include query string parameter contains attachments.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
commentCount:
description: Number of comments in the discussion.
type: number
createdBy:
description: >
`User` object containing `name` and `email` of the user who created
the discussion.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
lastCommentedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
lastCommentedUser:
description: >
`User` object containing `name` and `email` of the user who last
commented on the discussion.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
parentId:
description: The Id of the associated row or sheet.
type: number
parentType:
description: Type of parent object.
type: string
enum:
- ROW
- SHEET
readOnly:
description: Indicates whether the user can modify the discussion.
type: boolean
title:
description: Title automatically created by duplicating the first 100 characters
of top-level comment.
type: string
readOnly: true
Duration:
description: In a project sheet, represents a value in a duration cell, or a
lag value of a predecessor.
type: object
properties:
days:
description: The number of days for this duration.
type: number
elapsed:
description: If true, indicates this duration represents elapsed time, which
ignores non-working time.
type: boolean
hours:
description: The number of hours for this duration.
type: number
milliseconds:
description: The number of milliseconds for this duration.
type: number
minutes:
description: The number of minutes for this duration.
type: number
negative:
description: 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.
type: boolean
objectType:
type: string
enum:
- DURATION
seconds:
description: The number of seconds for this duration.
type: number
weeks:
description: The number of weeks for this duration.
type: number
Email:
type: object
properties:
ccMe:
description: Indicates whether to send a copy of the email to the sender.
type: boolean
message:
description: The message of the email.
type: string
sendTo:
description: Array of recipients.
type: array
items:
$ref: '#/components/schemas/AutomationAction/oneOf/1/properties/recipients/items'
subject:
description: The subject of the email.
type: string
Error:
description: The error caused by the failed item.
type: object
properties:
refId:
description: The Id of the specific error occurrence. Please include this
information when contacting Smartsheet support.
type: string
errorCode:
description: Custom error code from Smartsheet. See the complete [Error
Code List](../#section/Error-Code-List).
type: number
message:
description: Descriptive error message.
type: string
Event:
description: An Event object for event reporting.
type: object
properties:
eventId:
description: Unique event identifier.
type: string
example: 4b12345abc444def333g149he2b15b3j
objectType:
description: The Smartsheet resource impacted by the event, such as, SHEET
or WORKSPACE.
type: string
enum:
- SHEET
- WORKSPACE
example: sheet
action:
description: The action applied to the specified object, such as CREATE
or DELETE.
type: string
example: CREATE
objectId:
description: The identifier of the object impacted by the event.
type: string
example: 345678901234
eventTimeStamp:
description: Date and time of the event. Defaults to ISO-8601 format. See
dates and times for more information.
type: string
format: date-time
userId:
description: User assumed as the one who initiated the event. Usually the
userId property and the requestUserId property (below) have the same value.
However, if the request is an API call with Assume-User header then the
userId property identifies the user whose email matches the value in the
Assume-User header.
type: number
example: 123457654321
requestUserId:
description: User whose authentication credential is embedded in the request
that initiated the event. For example, if the request is an API call with
an access token then requestUserId identifies the user whose data can
be accessed via the access token (i.e., the user who authorized the creation
of the access token). On the other hand, if the request comes from a UI
session, then requestUserId identifies the user logged-in to the UI.
type: number
example: 133445566778
accessTokeName:
description: Name of the access token embedded in the request. This property
is omitted if there is no access token in the request (i.e., it isn't
an API call) or if the access token wasn't given a name when created (only
access tokens generated via the Smartsheet desktop UI can be given a name
at creation time).
type: number
nullable: true
source:
description: Identifies the type of action that triggered the event.
type: string
example: WEB_APP
additionalDetails:
description: Container object for additional event-specific properties.
Properties depend upon the event type. See [Event Reporting](https://smartsheet-platform.github.io/event-reporting-docs/)
reference documentation for details on each event type.
type: object
additionalProperties: true
Favorite:
type: object
properties:
objectId:
description: The Id of the favorited item. If type is template, only private
sheet-type template Id is allowed.
type: number
type:
type: string
enum:
- folder
- report
- sheet
- sight
- template
- workspace
Filters:
description: Smartsheet users can define and save personal column filters on
sheets they can view.
type: object
properties:
id:
description: Filters Id.
type: number
example: 52739485234
excludeSelected:
description: If true, rows containing cells matching the values or criteria
items are excluded instead of included.
type: boolean
example: false
filterType:
type: string
enum:
- PERSONAL
- SHARED
example: PERSONAL
query:
properties:
operator:
type: string
enum:
- AND
- OR
criteria:
description: Criteria objects specifying custom criteria against which
to match cell values.
type: array
items:
type: object
properties:
columnId:
description: Column Id.
type: number
example: 293452983475
operator:
description: Operator used to filter column values.
type: string
enum:
- BETWEEN
- CONTAINS
- EQUAL
- FUTURE
- GREATER_THAN
- IS_BLANK
- IS_CHECKED
- IS_DATE
- IS_NUMBER
- IS_NOT_BLANK
- IS_NOT_CHECKED
- IS_NOT_DATE
- IS_NOT_NUMBER
- LAST_N_DAYS
- LESS_THAN
- NEXT_N_DAYS
- NOT_EQUAL
- PAST
- TODAY
example: IS_ONE_OF
values:
description: Present if a custom filter criteria's operator has
one or more arguments.
type: array
items:
type: string
example:
- Complete
- In progress
includeParent:
description: If true, indicates that "show parent rows" is enabled for
the filters.
type: boolean
example:
operator: OR
criteria:
operator: IS_ONE_OF
values:
- Complete
- In Progress
columnId: 52793485233
includeParent: false
Folder:
description: Can contain dashboards, folders, reports, sheets, or templates.
type: object
properties:
id:
description: Folder Id.
type: number
favorite:
description: Returned only if the user has marked the folder as a favorite
in their "Home" tab (value = true).
type: boolean
folders:
description: Folders contained in folder.
type: array
items:
description: Can contain dashboards, folders, reports, sheets, or templates.
type: object
properties:
id:
description: Folder Id.
type: number
favorite:
description: Returned only if the user has marked the folder as a
favorite in their "Home" tab (value = true).
type: boolean
folders:
description: Folders contained in folder.
type: array
items:
$ref: '#/components/schemas/Folder/properties/folders/items'
name:
description: Folder name.
type: string
permalink:
description: URL that represents a direct link to the folder in Smartsheet.
type: string
reports:
description: Reports contained in folder.
type: array
items:
$ref: '#/components/schemas/Folder/properties/reports/items'
sheets:
description: Sheets contained in folder.
type: array
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
sights:
description: Dashboards contained in folder.
type: array
items:
$ref: '#/components/schemas/Folder/properties/sights/items'
templates:
description: Templates contained in folder.
type: array
items:
$ref: '#/components/schemas/Folder/properties/templates/items'
name:
description: Folder name.
type: string
permalink:
description: URL that represents a direct link to the folder in Smartsheet.
type: string
reports:
description: Reports contained in folder.
type: array
items:
allOf:
- $ref: '#/components/schemas/Folder/properties/sheets/items'
type: object
properties:
scope:
$ref: '#/components/schemas/Report/properties/scope'
sourceSheets:
type: array
description: An array of Sheet objects (without rows), representing
the sheets that rows in the report originated from. Only included
in the Get Report response if the include parameter specifies sourceSheets.
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
isSummaryReport:
type: boolean
description: A boolean to represent whether the report is a sheet
summary report or not. If this property is false, it is a row report.
proofs:
$ref: '#/components/schemas/Report/properties/proofs'
sheets:
description: Sheets contained in folder.
type: array
items:
type: object
properties:
id:
description: Sheet Id.
type: number
fromId:
description: The Id of the template from which to create the sheet.
This attribute can be specified in a request, but is never present
in a response.
type: number
ownerId:
description: User Id of the sheet owner.
type: number
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
attachments:
description: >
Array of Attachment objects.
Only returned if the [include](../../tag/sheets#operation/getSheet)
query string parameter contains **attachments**.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
columns:
type: array
items:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/columns/items'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
crossSheetReferences:
description: >
Array of CrossSheetReference objects.
Only returned if the [include](../../tag/sheets#operation/getSheet)
query string parameter contains **crossSheetReferences**.
type: array
items:
$ref: '#/components/schemas/Sheet/properties/crossSheetReferences/items'
dependenciesEnabled:
description: Indicates whether dependencies are enabled.
type: boolean
discussions:
description: >
Array of Discussion objects
Only returned if the [include](../../tag/sheets#operation/getSheet)
query string parameter contains **discussions**.
type: array
items:
$ref: '#/components/schemas/Proof/properties/discussions/items'
effectiveAttachmentOptions:
description: >
Array of enum strings (see
[Attachment.attachmentType](../../tag/attachmentsDescription)
indicating the allowable attachment options for the current
user and sheet.
type: array
items:
type: string
favorite:
description: Returned only if the user has marked this sheet as a
favorite in their Home tab (value = **true**).
type: boolean
ganttEnabled:
description: Indicates whether "Gantt View" is enabled.
type: boolean
hasSummaryFields:
description: Indicates whether a sheet summary is present.
type: boolean
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
name:
description: Sheet name.
type: string
owner:
description: Email address of the sheet owner.
type: string
permalink:
description: URL that represents a direct link to the sheet in Smartsheet.
type: string
projectSettings:
$ref: '#/components/schemas/Sheet/properties/projectSettings'
readOnly:
description: Returned only if the sheet belongs to an expired trial
(value = **true**).
type: boolean
resourceManagementEnabled:
description: Indicates that resource management is enabled.
type: boolean
rows:
type: array
items:
$ref: '#/components/schemas/ReportRow/allOf/0'
showParentRowsForFilters:
description: Returned only if there are column filters on the sheet.
Value = **true** if "show parent rows" is enabled for the filters.
type: boolean
source:
$ref: '#/components/schemas/Sheet/properties/source'
summary:
$ref: '#/components/schemas/Sheet/properties/summary'
totalRowCount:
description: The total number of rows in the sheet.
type: number
userPermissions:
$ref: '#/components/schemas/Sheet/properties/userPermissions'
userSettings:
$ref: '#/components/schemas/Sheet/properties/userSettings'
version:
description: A number that is incremented every time a sheet is modified.
type: number
workspace:
$ref: '#/components/schemas/Home/properties/workspaces/items'
sights:
description: Dashboards contained in folder.
type: array
items:
type: object
allOf:
- type: object
allOf:
- type: object
allOf:
- type: object
properties:
name:
description: Dashboard name.
type: string
properties:
id:
description: Dashboard Id.
type: number
readOnly: true
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
permalink:
description: URL that represents a direct link to the dashboard
in Smartsheet.
type: string
readOnly: true
properties:
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
properties:
backgroundColor:
description: The hex color, for instance `#E6F5FE`.
type: string
readOnly: true
columnCount:
description: Number of columns that the dashboard contains.
type: number
readOnly: true
favorite:
description: Indicates whether the user has marked the dashboard as
a favorite.
type: boolean
readOnly: true
source:
$ref: '#/components/schemas/Sheet/properties/source'
widgets:
readOnly: true
type: array
items:
$ref: '#/components/schemas/Sight/properties/widgets/items'
workspace:
$ref: '#/components/schemas/Home/properties/workspaces/items'
templates:
description: Templates contained in folder.
type: array
items:
description: A template can be used to create a sheet.
type: object
properties:
id:
description: Template Id.
type: number
type:
description: Type of template. Only applicable to public templates.
type: string
enum:
- report
- sheet
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
blank:
description: Indicates whether the template is blank. Only applicable
to public templates.
type: boolean
categories:
description: Indicates whether the template is blank. Only applicable
to public templates.
type: array
items:
type: string
description:
description: Template description.
type: string
globalTemplate:
description: Type of global template. Only applicable to blank public
templates.
type: string
enum:
- BLANK_SHEET
- PROJECT_SHEET
- TASK_LIST
image:
description: URL to the small preview image for this template. Only
applicable to non-blank public templates.
type: string
largeImage:
description: URL to the large preview image for this template. Only
applicable to non-blank public templates.
type: string
locale:
description: Locale of the template. Only applicable to public templates.
type: string
enum:
- ar_AE
- ar_BH
- ar_DZ
- ar_EG
- ar_IQ
- ar_JO
- ar_KW
- ar_LB
- ar_LY
- ar_MA
- ar_OM
- ar_QA
- ar_SA
- ar_SD
- ar_SY
- ar_TN
- ar_YE
- be_BY
- bg_BG
- ca_ES
- cs_CZ
- da_DK
- de_AT
- de_CH
- de_DE
- de_LU
- el_CY
- el_GR
- en_AU
- en_CA
- en_GB
- en_IE
- en_IN
- en_MT
- en_NZ
- en_PH
- en_SG
- en_US
- en_ZA
- es_AR
- es_BO
- es_CL
- es_CO
- es_CR
- es_DO
- es_EC
- es_ES
- es_GT
- es_HN
- es_MX
- es_NI
- es_PA
- es_PE
- es_PR
- es_PY
- es_SV
- es_US
- es_UY
- es_VE
- et_EE
- fi_FI
- fr_BE
- fr_CA
- fr_CH
- fr_FR
- fr_LU
- ga_IE
- hi_US
- hr_HR
- hu_HU
- in_ID
- is_IS
- it_CH
- it_IT
- iw_IL
- ja_JP
- ko_KR
- lt_LT
- lv_LV
- mk_MK
- ms_MY
- mt_MT
- nl_BE
- nl_NL
- no_NO
- pl_PL
- pt_BR
- pt_PT
- ro_RO
- ru_RU
- sk_SK
- sl_SI
- sq_AL
- sr_BA
- sr_CS
- sv_SE
- th_US
- tr_TR
- uk_UA
- vi_VN
- zh_CN
- zh_HK
- zh_SG
- zh_TW
name:
type: string
description: Type of global template.
example: Awesome Project Template
tags:
description: List of search tags for this template. Only applicable
to non-blank public templates.
type: array
items:
type: string
FontFamily:
type: object
properties:
name:
description: Name of the font family.
example: Arial
type: string
traits:
description: Platform-independent traits of the font family. Contains one
of the listed enum values.
example:
- sans-serif
type: array
items:
type: string
enum:
- sans-serif
- serif
FormatDetails:
type: object
properties:
paperSize:
description: Specifies paper size.
type: string
example: LETTER
enum:
- A0
- A1
- A2
- A3
- A4
- ARCHID
- LEGAL
- LETTER
- WIDE
FormatTables:
description: Contains all of the lookup tables that the format descriptor indexes
refer to. Here the examples show the formatting options, the default value
is used to denote each option. NOTE -- Indexes and their values are guaranteed
never to change or be removed for a given major API version. However, new
values could potentially be added to the ends of lookup tables. Because of
this possibility, your code should handle the case where a cell might contain
a format index value greater than the size of a lookup table your app has
loaded. Your application should check for that case and reload the format
tables if necessary.
type: object
properties:
defaults:
description: A format descriptor where each element describes the formats
the Smartsheet Web app displays for format values that have not been set.
Each value refers to an index of the following options.
type: string
example: ',,1,1,,,,,,,,,,,,,'
bold:
type: array
items:
type: string
example:
- none
- on
color:
description: The default setting is "none". Typically this is black text
and a white background.
type: array
items:
type: string
example:
- none
- transparent
- '#000000'
- '#0B347D'
- '#1061C3'
- '#237F2E'
- '#40B14B'
- '#592C00'
- '#5FB3F9'
- '#61058B'
- '#757575'
- '#7ED085'
- '#9210AD'
- '#974C00'
- '#991310'
- '#B9DDFC'
- '#BDBDBD'
- '#C6E7C8'
- '#D0AF8F'
- '#D190DA'
- '#E2F2FE'
- '#E5E5E5'
- '#E7F5E9'
- '#EA352E'
- '#EA5000'
- '#EBC700'
- '#EBC7EF'
- '#EEDCCA'
- '#F2E8DE'
- '#F4E4F5'
- '#F87E7D'
- '#FEFF00'
- '#FEFF85'
- '#FF8D00'
- '#FFCCD2'
- '#FFCD7A'
- '#FFE1AF'
- '#FFEBEE'
- '#FFED00'
- '#FFF3DF'
- '#FFFEE6'
- '#FFFFFF'
currency:
type: array
items:
type: object
properties:
code:
description: The ISO 4217 currency code.
example: EUR
type: string
symbol:
description: The currency symbol.
type: string
example: €
example:
- code: none
symbol: none
- code: ARS
symbol: $
- code: AUD
symbol: $
- code: BRL
symbol: R$
- code: CAD
symbol: $
- code: CHF
symbol: CHF
- code: CLP
symbol: $
- code: CNY
symbol: ¥
- code: DKK
symbol: kr.
- code: EUR
symbol: €
- code: GBP
symbol: £
- code: HKD
symbol: $
- code: ILS
symbol: ₪
- code: INR
symbol: ₹
- code: JPY
symbol: ¥
- code: KRW
symbol: ₩
- code: MXN
symbol: $
- code: NOK
symbol: kr
- code: NZD
symbol: $
- code: RUB
symbol: ₽
- code: SEK
symbol: kr
- code: SGD
symbol: $
- code: USD
symbol: $
- code: ZAR
symbol: R
dateFormat:
type: array
items:
type: string
example:
- LOCALE_BASED
- MMMM_D_YYYY
- MMM_D_YYYY
- D_MMM_YYYY
- YYYY_MM_DD_HYPHEN
- YYYY_MM_DD_DOT
- DWWWW_MMMM_D_YYYY
- DWWW_DD_MMM_YYYY
- DWWW_MM_DD_YYYY
- MMMM_D
- D_MMMM
decimalCount:
type: array
items:
type: string
example:
- '0'
- '1'
- '2'
- '3'
- '4'
- '5'
fontFamily:
type: array
items:
type: object
properties:
name:
description: Name of the font family.
example: Arial
type: string
traits:
description: Platform-independent traits of the font family. Contains
one of the listed enum values.
example:
- sans-serif
type: array
items:
type: string
enum:
- sans-serif
- serif
example:
- name: Arial
traits:
- sans-serif
- name: Roboto
traits:
- sans-serif
- name: Tahoma
traits:
- sans-serif
- name: Times New Roman
traits:
- serif
- name: Verdana
traits:
- sans-serif
fontSize:
type: array
items:
type: string
example:
- '8'
- '9'
- '10'
- '12'
- '14'
- '16'
- '18'
- '20'
- '24'
- '28'
- '32'
- '36'
horizontalAlign:
description: The default setting is "default" which is equivalent to "left".
type: array
items:
type: string
example:
- default
- left
- center
- right
italic:
type: array
items:
type: string
example:
- none
- on
numberFormat:
type: array
items:
type: string
example:
- none
- NUMBER
- CURRENCY
- PERCENT
strikethrough:
type: array
items:
type: string
example:
- none
- on
textWrap:
type: array
items:
type: string
example:
- none
- on
thousandsSeparator:
type: array
items:
type: string
example:
- none
- on
underline:
type: array
items:
type: string
example:
- none
- on
verticalAlign:
description: The default setting is "default" which is equivalent to "top".
type: array
items:
type: string
example:
- default
- top
- middle
- bottom
Group:
type: object
properties:
id:
description: Group Id.
type: number
example: 4583173393803140
name:
description: Group name.
type: string
example: Group 1
description:
description: Group description.
type: string
example: My group
owner:
description: Group owner’s email address.
type: string
format: email
example: john.doe@smartsheet.com
ownerId:
description: Group owner's user Id.
type: number
example: 2331373580117892
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
GroupMember:
type: object
properties:
id:
description: Group member's user Id.
type: number
example: 2331373580117892
email:
description: Group member's email address.
type: string
format: email
example: john.doe@smartsheet.com
firstName:
description: Group member's first name.
type: string
example: John
lastName:
description: Group member's last name.
type: string
example: Doe
name:
description: Group member's full name.
type: string
example: John Doe
Home:
description: All objects a user has access to, including dashboards, folders,
reports, sheets, templates, and workspaces.
type: object
properties:
folders:
type: array
items:
$ref: '#/components/schemas/Folder/properties/folders/items'
reports:
type: array
items:
$ref: '#/components/schemas/Folder/properties/reports/items'
sheets:
type: array
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
sights:
type: array
items:
$ref: '#/components/schemas/Folder/properties/sights/items'
templates:
type: array
items:
$ref: '#/components/schemas/Folder/properties/templates/items'
workspaces:
type: array
items:
description: Can contain dashboards, folders, reports, sheets, and templates.
type: object
properties:
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
id:
description: Workspace Id.
type: number
favorite:
description: Returned only if the user has marked the workspace as
a favorite in their "Home" tab (value = true).
type: boolean
folders:
description: Folders contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/folders/items'
name:
description: Workspace name.
type: string
permalink:
description: URL that represents a direct link to the workspace in
Smartsheet.
type: string
reports:
description: Reports contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/reports/items'
sheets:
description: Sheets contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
sights:
description: Dashboards contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/sights/items'
templates:
description: Templates contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/templates/items'
Hyperlink:
type: object
properties:
reportId:
type: number
description: If non-null, this hyperlink is a link to the report with this
Id.
sheetId:
type: number
description: If non-null, this hyperlink is a link to the sheet with this
Id.
sightId:
type: number
description: If non-null, this hyperlink is a link to the dashboard with
this Id.
url:
type: string
description: 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.
Image:
type: object
properties:
altText:
type: string
description: Alternate text for the image.
height:
type: number
description: Original height (in pixels) of the uploaded image.
id:
type: string
description: Image Id.
width:
type: number
description: Original width (in pixels) of the uploaded image.
ImageUrl:
type: object
properties:
imageId:
description: Image Id.
type: string
error:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
height:
description: Image height in pixels.
type: number
url:
description: 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.
type: string
width:
description: Image width in pixels.
type: number
ImageUrlMap:
type: object
properties:
imageUrls:
type: array
items:
type: object
properties:
imageId:
description: Image Id.
type: string
error:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
height:
description: Image height in pixels.
type: number
url:
description: 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.
type: string
width:
description: Image width in pixels.
type: number
urlExpiresInMillis:
description: Milliseconds before the URLs within imageUrls expire.
type: number
ImageWidgetContent:
type: object
title: Image
properties:
type:
type: string
enum:
- IMAGE
privateId:
description: The image private Id.
type: string
fileName:
description: Name of the image file.
type: string
format:
description: Format descriptor. Follows the pattern in FormatTables.
type: string
example: ',7,1,,,,2,2,1,3,,,,,,1,'
height:
type: number
hyperlink:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/hyperlink'
width:
description: Original width of the image in pixels.
type: number
IndexResult:
type: object
properties:
pageNumber:
description: 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.
type: number
example: 1
readOnly: true
pageSize:
description: 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.
type: number
example: 50
nullable: true
readOnly: true
totalPages:
description: The total number of pages in the full result set.
type: number
example: 25
readOnly: true
totalCount:
description: The total number of items in the full result set.
type: number
example: 136
readOnly: true
MiniUser:
description: MiniUser Object
type: object
properties:
email:
type: string
format: email
example: jane.doe@smartsheet.com
name:
type: string
readOnly: true
example: Jane Doe
MultiRowEmail:
allOf:
- allOf:
- $ref: '#/components/schemas/ProofRequestBody/allOf/0'
type: object
properties:
columnIds:
description: The Id of the columns to be included.
type: array
items:
type: number
includeAttachments:
description: Indicates whether to include attachments in the email.
type: boolean
includeDiscussions:
description: Indicates whether to include discussions in the email.
type: boolean
layout:
description: >
One of the following values: **HORIZONTAL** or **VERTICAL**.
Optional, defaults to **HORIZONTAL** when multiple rows are
being sent and to **VERTICAL** when a single row is being sent.
**HORIZONTAL** formats the rows being sent as a grid, whereas
**VERTICAL** formats the rows being sent as separate cards.
type: boolean
type: object
properties:
rowIds:
description: The Ids of rows to be included.
type: array
items:
type: number
ObjectValue:
description: 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.
type: object
properties:
objectType:
type: string
enum:
- ABSTRACT_DATETIME
- CONTACT
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT
- MULTI_PICKLIST
- PREDECESSOR_LIST
Predecessor:
type: object
properties:
rowId:
description: The Id of the predecessor row.
type: number
type:
description: >
Type of the predecessor:
* FF (Finish-to-Finish) - finish at the same time the predecessor finishes.
* FS (Finish-to-Start) - start after the predecessor finishes.
* SF (Start-to-Finish) - finish before the predecessor starts.
* SS (Start-to-Start) - start at the same time the predecessor starts.
type: string
enum:
- FF
- FS
- SF
- SS
inCriticalPath:
description: True if this predecessor is in the critical path.
type: boolean
readOnly: true
invalid:
description: 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.
type: boolean
readOnly: true
lag:
description: In a project sheet, represents a value in a duration cell,
or a lag value of a predecessor.
type: object
properties:
days:
description: The number of days for this duration.
type: number
elapsed:
description: If true, indicates this duration represents elapsed time,
which ignores non-working time.
type: boolean
hours:
description: The number of hours for this duration.
type: number
milliseconds:
description: The number of milliseconds for this duration.
type: number
minutes:
description: The number of minutes for this duration.
type: number
negative:
description: 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.
type: boolean
objectType:
type: string
enum:
- DURATION
seconds:
description: The number of seconds for this duration.
type: number
weeks:
description: The number of weeks for this duration.
type: number
rowNumber:
description: The row number of the predecessor row. Omitted if invalid is
true.
type: number
readOnly: true
PredecessorList:
allOf:
- $ref: '#/components/schemas/Cell/properties/objectValue'
type: object
properties:
objectType:
type: string
enum:
- PREDECESSOR_LIST
predecessors:
type: array
items:
type: object
properties:
rowId:
description: The Id of the predecessor row.
type: number
type:
description: >
Type of the predecessor:
* FF (Finish-to-Finish) - finish at the same time the predecessor
finishes.
* FS (Finish-to-Start) - start after the predecessor finishes.
* SF (Start-to-Finish) - finish before the predecessor starts.
* SS (Start-to-Start) - start at the same time the predecessor
starts.
type: string
enum:
- FF
- FS
- SF
- SS
inCriticalPath:
description: True if this predecessor is in the critical path.
type: boolean
readOnly: true
invalid:
description: 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.
type: boolean
readOnly: true
lag:
$ref: '#/components/schemas/Predecessor/properties/lag'
rowNumber:
description: The row number of the predecessor row. Omitted if invalid
is true.
type: number
readOnly: true
ProjectSettings:
description: Represents the project settings dependencies for a specific sheet.
Project settings may be updated on sheets that the user has editor access.
type: object
properties:
lengthOfDay:
description: Length of a workday for a project sheet.
type: number
minimum: 1
maximum: 24
nonWorkingDays:
description: Non-working days for a project sheet.
type: array
items:
type: string
format: date
workingDays:
type: array
items:
type: string
enum:
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
- SUNDAY
Proof:
description: Proof Object
type: object
properties:
id:
description: Proof Id of the proof version.
type: number
originalId:
description: Proof Id of the original proof version.
type: number
name:
description: Proof name. This is the same as primary column value. If the
primary column value is empty, name is empty.
type: string
proofType:
description: File type for the proof version.
type: string
enum:
- DOCUMENT
- IMAGE
- MIXED
- NONE
- VIDEO
proofRequestUrl:
description: URL to review a proofing request.
type: string
version:
description: The version number of the proof.
type: number
lastUpdatedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
lastUpdatedBy:
description: >
`User` object containing `name` and `email` of the user who last
updated the proof.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
isCompleted:
description: Indicates whether the proof is completed.
type: boolean
attachments:
description: Array of Attachment objects. Only returned if the include query
string parameter contains attachments.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
discussions:
description: Array of Discussion objects. Only returned if the include query
string parameter contains discussions.
type: array
items:
type: object
properties:
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
id:
description: Discussion Id.
type: number
comments:
description: Array of comments in discussion. Only returned if the
include query string parameter contains comments.
type: array
items:
$ref: '#/components/schemas/Discussion/properties/comments/items'
commentAttachments:
description: Array of attachments on discussion comments. Only returned
if the include query string parameter contains attachments.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
commentCount:
description: Number of comments in the discussion.
type: number
createdBy:
description: >
`User` object containing `name` and `email` of the user who
created the discussion.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
lastCommentedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
lastCommentedUser:
description: >
`User` object containing `name` and `email` of the user who
last commented on the discussion.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
parentId:
description: The Id of the associated row or sheet.
type: number
parentType:
description: Type of parent object.
type: string
enum:
- ROW
- SHEET
readOnly:
description: Indicates whether the user can modify the discussion.
type: boolean
title:
description: Title automatically created by duplicating the first
100 characters of top-level comment.
type: string
readOnly: true
ProofRequest:
allOf:
- allOf:
- $ref: '#/components/schemas/ProofRequestBody/allOf/0'
type: object
properties:
isDownloadable:
description: Whether the description is downloadable.
type: boolean
type: object
properties:
id:
description: Proof request Id.
type: number
proofId:
description: Proof Id of the original proof.
type: number
sentBy:
description: |
`User` object containing `name` and `email` of the sender.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
sentAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
isDownloadable:
description: Indicates whether the description is downloadable.
type: boolean
status:
description: Proof request status.
type: string
enum:
- ACTIVE
- EXPIRED
- PROOF_DELETED
ProofRequestAction:
type: object
properties:
user:
description: >
`User` object containing `name` and `email` of the user performing
the action.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
actionStatus:
description: Proof request action status.
type: string
enum:
- APPROVED
- PENDING
- REJECTED
ProofRequestBody:
allOf:
- type: object
properties:
ccMe:
description: Indicates whether to send a copy of the email to the sender.
type: boolean
message:
description: The message of the email.
type: string
sendTo:
description: Array of recipients.
type: array
items:
$ref: '#/components/schemas/AutomationAction/oneOf/1/properties/recipients/items'
subject:
description: The subject of the email.
type: string
type: object
properties:
isDownloadable:
description: Whether the description is downloadable.
type: boolean
Recipient:
description: >
Specifies the recipient of an email. The recipient may be either an
individual or a group. To specify an individual, set the email
attribute; to specify a group, set the groupId attribute. Either email
and groupId may be set, but not both.
oneOf:
- type: object
description: >
Specifies the recipient of an [Email]($ref:
'Email.yaml#/components/schemas/Email'). The recipient may be either
an individual or a group. To specify an individual, set the
**email** attribute; to specify a group, set the **groupId**
attribute. Either **email** and **groupId** may be set, but not
both.
properties:
email:
description: The email address of an individual recipient.
type: string
format: email
example: john.doe@smartsheet.com
- type: object
description: >
Specifies the recipient of an [Email]($ref:
'Email.yaml#/components/schemas/Email'). The recipient may be either
an individual or a group. To specify an individual, set the
**email** attribute; to specify a group, set the **groupId**
attribute. Either **email** and **groupId** may be set, but not
both.
properties:
groupId:
description: The Id of a group recipient.
type: number
example: 2258118617917316
Report:
allOf:
- $ref: '#/components/schemas/Folder/properties/sheets/items'
type: object
properties:
scope:
type: object
properties:
sheets:
description: >
Array of Sheet objects (containing just the sheet Id) of any
sheets that the requester has access to that make up the report.
type: array
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
workspaces:
description: >
Array of Workspace objects (containing just the workspace Id)
that the requester has access to that make up the report.
type: array
items:
$ref: '#/components/schemas/Home/properties/workspaces/items'
sourceSheets:
type: array
description: An array of Sheet objects (without rows), representing the
sheets that rows in the report originated from. Only included in the Get
Report response if the include parameter specifies sourceSheets.
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
isSummaryReport:
type: boolean
description: A boolean to represent whether the report is a sheet summary
report or not. If this property is false, it is a row report.
proofs:
description: Report Proof Object
type: object
properties:
id:
description: Proof Id of the proof version.
type: number
originalId:
description: Proof Id of the original proof version.
type: number
name:
description: Proof name. This is the same as primary column value. If
the primary column value is empty, name is empty.
type: string
type:
description: File type for the proof version.
type: string
enum:
- DOCUMENT
- IMAGE
- MIXED
- NONE
- VIDEO
documentType:
description: Document type for the proof version.
type: string
enum:
- PDF
- VIDEO
- WORD
- POWERPOINT
- EXCEL
- IMAGE
proofRequestUrl:
description: URL to review a proofing request.
type: string
version:
description: The version number of the proof.
type: number
lastUpdatedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
lastUpdatedBy:
description: >
`User` object containing `name` and `email` of the user who last
updated the proof.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
isCompleted:
description: Indicates whether the proof is completed.
type: boolean
ReportCell:
allOf:
- $ref: '#/components/schemas/CellDataItem/properties/cell'
type: object
properties:
virtualColumnId:
type: number
description: This property refers to the cell's parent column in the report,
while the columnId property refers to the cell's parent column in its
originating source sheet.
ReportColumn:
allOf:
- $ref: '#/components/schemas/CellLinkWidgetContent/properties/columns/items'
type: object
properties:
virtualId:
description: The virtual Id of this report column.
type: number
sheetNameColumn:
description: Returns true only for the special "Sheet Name" report column.
type: boolean
ReportPublish:
type: object
properties:
readOnlyFullAccessibleBy:
description: >
Indicates who can access the 'Read-Only Full' view of the published
report:
* If **ALL**, it is available to anyone who has the link.
* If **ORG**, it is available only to members of the report owner's Smartsheet
organization account.
* If **SHARED**, it is available only to users shared to the item.
Only returned in a response if **readOnlyFullEnabled** = **true**.
type: string
readOnlyFullDefaultView:
description: >
Indicates which view the user has set for a read-only, default view
of the published report. Must be one of
the following values: **CALENDAR**, **CARD**, or **GRID**.
type: string
readOnlyFullEnabled:
description: >
(Required) If **true**, a rich version of the report is published
with the ability to download row
attachments and discussions.
type: boolean
readOnlyFullShowToolbar:
deprecated: true
description: >
Indicates whether the left nav toolbar is displayed. The default, or
**true**, is to display the toolbar.
If **false**, hides the toolbar.
type: boolean
readOnlyFullUrl:
description: |
URL for 'Read-Only Full' view of the published report.
Only returned in a response if **readOnlyFullEnabled** = **true**.
type: string
ReportRow:
allOf:
- type: object
properties:
id:
description: Row Id.
type: number
sheetId:
description: Parent sheet Id.
type: number
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
attachments:
description: Attachments on row. Only returned if the include query string
parameter contains attachments.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
cells:
description: Cells belonging to the row.
type: array
items:
$ref: '#/components/schemas/CellDataItem/properties/cell'
columns:
description: Columns of row. Only returned if the include query string
parameter contains columns.
type: array
items:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/columns/items'
conditionalFormat:
description: Describes this row's conditional format. Only returned if
the include query string parameter contains format and this row has
a conditional format applied.
type: string
example: ',,1,1,,,,,,,,,,,,,'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: User object containing name and email of the creator of this
row.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
discussions:
description: Discussions on the row. Only returned if the include query
string parameter contains discussions.
type: array
items:
$ref: '#/components/schemas/Proof/properties/discussions/items'
proofs:
description: Proof on row. Only returned if the include query string parameter
contains proofs.
$ref: '#/components/schemas/Row/properties/proofs'
expanded:
description: Indicates whether the row is expanded or collapsed.
type: boolean
filteredOut:
description: Indicates if the row is filtered out by a column filter.
Only returned if the include query string parameter contains filters.
type: boolean
format:
description: Format descriptor. Only returned if the include query string
parameter contains format and this row has a non-default format applied.
type: string
example: ',,1,1,,,,,,,,,,,,,'
inCriticalPath:
description: Only returned, with a value of true, if the sheet is a project
sheet with dependencies enabled and this row is in the critical path.
type: boolean
locked:
description: Indicates whether the row is locked.
type: boolean
lockedForUser:
description: Indicates whether the row is locked for the requesting user.
type: boolean
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedBy:
description: User object containing name and email of the last person
to modify this row.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
permaLink:
description: URL that represents a direct link to the row in Smartsheet.
Only returned if the include query string parameter contains rowPermalink.
type: string
rowNumber:
description: Row number within the sheet.
type: number
minimum: 1
version:
description: Sheet version number that is incremented every time a sheet
is modified.
type: number
type: object
properties:
sheetId:
type: number
description: The Id of the sheet from which the row originates.
ReportWidgetContent:
type: object
title: Report
properties:
type:
type: string
enum:
- GRIDGANTT
reportId:
description: Report Id denoting container source.
type: number
htmlContent:
description: HTMl snippet to render report.
type: string
backgroundColor:
description: The hex color.
example: '#E6F5FE'
type: string
hyperlink:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/hyperlink'
Result:
type: object
allOf:
- type: object
allOf:
- type: object
properties:
message:
description: Message that indicates the outcome of the request. (One
of SUCCESS or PARTIAL_SUCCESS.)
type: string
enum:
- PARTIAL_SUCCESS
- SUCCESS
example: SUCCESS
resultCode:
description: |-
* '0' Success
* '3' Partial Success of Bulk Operation
type: number
enum:
- 0
- 3
properties:
failedItems:
description: Array of BulkItemFailure objects which represents the items
that failed to be added or updated. See [Partial Success](/partial-success)
for more information. Applicable only for bulk operations that support
partial success.
type: array
items:
type: object
properties:
rowId:
description: The Id of the row that failed. Applicable only to bulk
row operations.
type: number
nullable: true
error:
$ref: '#/components/schemas/BulkItemFailure/properties/error'
index:
description: The index of the failed item in the bulk request array.
type: number
nullable: true
properties:
version:
description: New version of the sheet. Applicable only for operations which
update sheet data.
type: number
nullable: true
RichTextWidgetContent:
type: object
title: Rich Text
properties:
type:
type: string
enum:
- RICHTEXT
htmlContent:
description: >
The widget contents as HTML. The Rich Text widget supports the
following subset of HTML tags and CSS Styles:
HTML
* a - hyperlink
* br - line break
* li - list item
* ol - ordered list
* p - paragraph
* span - section of the document
* ul - unordered list
CSS
* color
* font-family
* font-size
* font-style
* font-weight
* text-align
* text-decoration
type: string
Row:
type: object
properties:
id:
description: Row Id.
type: number
sheetId:
description: Parent sheet Id.
type: number
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
attachments:
description: Attachments on row. Only returned if the include query string
parameter contains attachments.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
cells:
description: Cells belonging to the row.
type: array
items:
$ref: '#/components/schemas/CellDataItem/properties/cell'
columns:
description: Columns of row. Only returned if the include query string parameter
contains columns.
type: array
items:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/columns/items'
conditionalFormat:
description: Describes this row's conditional format. Only returned if the
include query string parameter contains format and this row has a conditional
format applied.
type: string
example: ',,1,1,,,,,,,,,,,,,'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: User object containing name and email of the creator of this
row.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
discussions:
description: Discussions on the row. Only returned if the include query
string parameter contains discussions.
type: array
items:
$ref: '#/components/schemas/Proof/properties/discussions/items'
proofs:
description: Proof Object
type: object
properties:
id:
description: Proof Id of the proof version.
type: number
originalId:
description: Proof Id of the original proof version.
type: number
name:
description: Proof name. This is the same as primary column value. If
the primary column value is empty, name is empty.
type: string
proofType:
description: File type for the proof version.
type: string
enum:
- DOCUMENT
- IMAGE
- MIXED
- NONE
- VIDEO
proofRequestUrl:
description: URL to review a proofing request.
type: string
version:
description: The version number of the proof.
type: number
lastUpdatedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
lastUpdatedBy:
description: >
`User` object containing `name` and `email` of the user who last
updated the proof.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
isCompleted:
description: Indicates whether the proof is completed.
type: boolean
attachments:
description: Array of Attachment objects. Only returned if the include
query string parameter contains attachments.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
discussions:
description: Array of Discussion objects. Only returned if the include
query string parameter contains discussions.
type: array
items:
$ref: '#/components/schemas/Proof/properties/discussions/items'
expanded:
description: Indicates whether the row is expanded or collapsed.
type: boolean
filteredOut:
description: Indicates if the row is filtered out by a column filter. Only
returned if the include query string parameter contains filters.
type: boolean
format:
description: Format descriptor. Only returned if the include query string
parameter contains format and this row has a non-default format applied.
type: string
example: ',,1,1,,,,,,,,,,,,,'
inCriticalPath:
description: Only returned, with a value of true, if the sheet is a project
sheet with dependencies enabled and this row is in the critical path.
type: boolean
locked:
description: Indicates whether the row is locked.
type: boolean
lockedForUser:
description: Indicates whether the row is locked for the requesting user.
type: boolean
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedBy:
description: User object containing name and email of the last person to
modify this row.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
permaLink:
description: URL that represents a direct link to the row in Smartsheet.
Only returned if the include query string parameter contains rowPermalink.
type: string
rowNumber:
description: Row number within the sheet.
type: number
minimum: 1
version:
description: Sheet version number that is incremented every time a sheet
is modified.
type: number
RowEmail:
allOf:
- $ref: '#/components/schemas/ProofRequestBody/allOf/0'
type: object
properties:
columnIds:
description: The Id of the columns to be included.
type: array
items:
type: number
includeAttachments:
description: Indicates whether to include attachments in the email.
type: boolean
includeDiscussions:
description: Indicates whether to include discussions in the email.
type: boolean
layout:
description: >
One of the following values: **HORIZONTAL** or **VERTICAL**.
Optional, defaults to **HORIZONTAL** when multiple rows are being
sent and to **VERTICAL** when a single row is being sent.
**HORIZONTAL** formats the rows being sent as a grid, whereas
**VERTICAL** formats the rows being sent as separate cards.
type: boolean
RowMapping:
type: object
properties:
from:
description: Row Id in the source sheet.
type: number
to:
description: Row Id in the destination sheet.
type: number
Schedule:
type: object
properties:
type:
description: Type of schedule.
type: string
enum:
- ONCE
- DAILY
- WEEKLY
- MONTHLY
- YEARLY
dayDescriptors:
description: >
A string array consists of one or more of the following values:
* **DAY**, **WEEKDAY**, **WEEKEND**
* **SUNDAY**, **MONDAY**, **TUESDAY**, **WEDNESDAY**, **THURSDAY**, **FRIDAY**,
**SATURDAY**
The subset of values applicable to the schedule type are as followed:
| Value | Daily schedule | Weekly schedule | Monthly schedule
|
|---------------|----------------|-----------------|------------------|
| **DAY** | | | **✓** |
| **WEEKDAY** | **✓** | | **✓** |
| **WEEKEND** | | | **✓** |
| **SUNDAY** | | **✓** | **✓** |
| **MONDAY** | | **✓** | **✓** |
| **TUESDAY** | | **✓** | **✓** |
| **WEDNESDAY** | | **✓** | **✓** |
| **THURSDAY** | | **✓** | **✓** |
| **FRIDAY** | | **✓** | **✓** |
| **SATURDAY** | | **✓** | **✓** |
For more details, refer to the Table of Schedule Object’s Attributes below.
type: array
items:
type: string
enum:
- DAY
- WEEKDAY
- WEEKEND
- SUNDAY
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
dayOfMonth:
description: >
The day within the month.
Valid range is 1 to 28.
This attribute is applicable to the following schedule type:
* **MONTHLY**
For more details, refer to the Table of Schedule Object’s Attributes below.
type: number
minimum: 1
maximum: 31
dayOrdinal:
description: >
Must be one of the following values:
* **FIRST** or **LAST**
* **SECOND**, **THIRD**, or **FOURTH**
This attribute is applicable to the following schedule type:
* **MONTHLY**
For more details, refer to the Table of Schedule Object’s Attributes
below.
type: string
enum:
- FIRST
- LAST
- SECOND
- THIRD
- FOURTH
repeatEvery:
description: >
Frequency on which the request is delivered. The unit is a function
of the **type** attribute. For example,
for **MONTHLY** schedule, **repeatEvery=1** means every month.
Valid range is 1 to 99.
This attribute is applicable to the following schedule types: **DAILY**,
**WEEKLY**, **MONTHLY**, or **YEARLY**.
For more details, refer to the Table of Schedule Object’s Attributes below.
type: number
minimum: 1
maximum: 99
endAt:
allOf:
- description: >
The date, time, and time zone at which the delivery schedule
ends.
The value is either in a string format or a numeric format:
* When the value is a string, it must be a valid ISO-8601 date and time
with an offset (YYYY-MM-DDThh:mm:ssTZD).
* When the value is a number, it represents a date and time with no
offset (UTC time zone). See Dates and Times for more information.
The value must be later than startAt and the current date and time.
The value must contain zero hours, zero minutes, and zero seconds.
The offset (time zone) value must be the same as the offset (time zone)
value in startAt.
This attribute is applicable to the following schedule types: DAILY,
WEEKLY, MONTHLY, YEARLY. For more details, refer to the Table of Schedule
Object’s Attributes below.
- oneOf:
- type: string
format: date-time
- type: number
lastSentAt:
allOf:
- description: The date and time for when the last request was sent.
- $ref: '#/components/schemas/Attachment/properties/createdAt'
nextSendAt:
allOf:
- description: The date and time for when the next request is scheduled
to send.
- $ref: '#/components/schemas/Attachment/properties/createdAt'
startAt:
allOf:
- description: >
The date, time, and time zone at which the first delivery
starts.
The value is either in a string format or a numeric format:
* When the value is a string, it must be a valid ISO-8601 date and
time with an offset (YYYY-MM-DDThh:mm:ssTZD).
* When the value is a number, it represents a date and time with
no offset (UTC time zone). See [Dates and Times](../../#section/API-Basics/Dates-and-Times)
for more information.
For ONCE schedule type, it must be later than the current date time.
For all other schedule types, it must be later than “2000-01-01T00:00:00Z”
in string format or 946684800000 in numeric format.
The value must contain zero minutes and zero seconds.
This attribute is applicable to all schedule types.
For more details, refer to the Table of Schedule Object’s Attributes
below.
- $ref: '#/components/schemas/Schedule/properties/endAt/allOf/1'
Scope:
type: object
properties:
sheets:
description: >
Array of Sheet objects (containing just the sheet Id) of any sheets
that the requester has access to that make up the report.
type: array
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
workspaces:
description: >
Array of Workspace objects (containing just the workspace Id) that
the requester has access to that make up the report.
type: array
items:
$ref: '#/components/schemas/Home/properties/workspaces/items'
SearchResult:
type: object
properties:
results:
description: Array of SearchResultItem objects.
type: array
items:
type: object
properties:
objectId:
description: Search result object Id.
type: number
parentObjectId:
description: Search result parent object Id.
type: number
contextData:
description: Additional info on search result context.
type: array
items:
type: string
objectType:
description: Search result object type (attachment, dashboard, discussion,
folder, report, row, sheet, summaryField, template, or workspace).
type: string
parentObjectName:
description: Search result parent object name.
type: string
parentObjectType:
description: Search result parent object type (dashboard, folder,
report, sheet, template, or workspace).
type: string
proofUrl:
description: The proofUrl string will be present in the contextData
if the discussion or attachment belongs to a proof.
type: string
text:
description: Search result text excerpt.
type: string
totalCount:
description: Total number of search results.
type: number
SearchResultItem:
type: object
properties:
objectId:
description: Search result object Id.
type: number
parentObjectId:
description: Search result parent object Id.
type: number
contextData:
description: Additional info on search result context.
type: array
items:
type: string
objectType:
description: Search result object type (attachment, dashboard, discussion,
folder, report, row, sheet, summaryField, template, or workspace).
type: string
parentObjectName:
description: Search result parent object name.
type: string
parentObjectType:
description: Search result parent object type (dashboard, folder, report,
sheet, template, or workspace).
type: string
proofUrl:
description: The proofUrl string will be present in the contextData if the
discussion or attachment belongs to a proof.
type: string
text:
description: Search result text excerpt.
type: string
SelectionRange:
description: Defines a block of cells in a sheet.
type: object
properties:
sourceColumnId1:
description: Defines beginning edge of range when specifying one or more
columns.
type: number
sourceColumnId2:
description: Defines ending edge of range when specifying one or more columns.
type: number
sourceRowId1:
description: Defines beginning edge of range when specifying one or more
rows.
type: number
sourceRowId2:
description: Defines ending edge of range when specifying one or more rows.
type: number
SentUpdateRequest:
type: object
properties:
id:
description: The Id of the sent update request.
type: number
columnIds:
description: The Ids of columns included in the request.
type: array
items:
type: number
rowIds:
description: The Ids of rows where an update is requested.
type: array
items:
type: number
updateRequestId:
description: The Id of the originating update request.
type: number
includeAttachments:
description: Indicates whether the attachments were included in the email.
type: boolean
includeDiscussions:
description: Indicates whether the discussions were included in the email.
type: boolean
message:
description: The message of the email. Max 10000 characters.
type: string
sentAt:
description: The date and time for when the sent update request was sent
to the recipient.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
sentBy:
description: |
`User` object containing `name` and `email` of the sender.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
sentTo:
description: Recipient object.
allOf:
- $ref: '#/components/schemas/AutomationAction/oneOf/1/properties/recipients/items'
status:
description: The status of the sent update request.
type: string
enum:
- CANCELED
- COMPLETE
- PENDING
subject:
description: The subject of the email.
type: string
ServerInfo:
type: object
properties:
formats:
description: Contains all of the lookup tables that the format descriptor
indexes refer to. Here the examples show the formatting options, the default
value is used to denote each option. NOTE -- Indexes and their values
are guaranteed never to change or be removed for a given major API version. However,
new values could potentially be added to the ends of lookup tables. Because
of this possibility, your code should handle the case where a cell might
contain a format index value greater than the size of a lookup table your
app has loaded. Your application should check for that case and reload
the format tables if necessary.
type: object
properties:
defaults:
description: A format descriptor where each element describes the formats
the Smartsheet Web app displays for format values that have not been
set. Each value refers to an index of the following options.
type: string
example: ',,1,1,,,,,,,,,,,,,'
bold:
type: array
items:
type: string
example:
- none
- on
color:
description: The default setting is "none". Typically this is black
text and a white background.
type: array
items:
type: string
example:
- none
- transparent
- '#000000'
- '#0B347D'
- '#1061C3'
- '#237F2E'
- '#40B14B'
- '#592C00'
- '#5FB3F9'
- '#61058B'
- '#757575'
- '#7ED085'
- '#9210AD'
- '#974C00'
- '#991310'
- '#B9DDFC'
- '#BDBDBD'
- '#C6E7C8'
- '#D0AF8F'
- '#D190DA'
- '#E2F2FE'
- '#E5E5E5'
- '#E7F5E9'
- '#EA352E'
- '#EA5000'
- '#EBC700'
- '#EBC7EF'
- '#EEDCCA'
- '#F2E8DE'
- '#F4E4F5'
- '#F87E7D'
- '#FEFF00'
- '#FEFF85'
- '#FF8D00'
- '#FFCCD2'
- '#FFCD7A'
- '#FFE1AF'
- '#FFEBEE'
- '#FFED00'
- '#FFF3DF'
- '#FFFEE6'
- '#FFFFFF'
currency:
type: array
items:
$ref: '#/components/schemas/FormatTables/properties/currency/items'
example:
- code: none
symbol: none
- code: ARS
symbol: $
- code: AUD
symbol: $
- code: BRL
symbol: R$
- code: CAD
symbol: $
- code: CHF
symbol: CHF
- code: CLP
symbol: $
- code: CNY
symbol: ¥
- code: DKK
symbol: kr.
- code: EUR
symbol: €
- code: GBP
symbol: £
- code: HKD
symbol: $
- code: ILS
symbol: ₪
- code: INR
symbol: ₹
- code: JPY
symbol: ¥
- code: KRW
symbol: ₩
- code: MXN
symbol: $
- code: NOK
symbol: kr
- code: NZD
symbol: $
- code: RUB
symbol: ₽
- code: SEK
symbol: kr
- code: SGD
symbol: $
- code: USD
symbol: $
- code: ZAR
symbol: R
dateFormat:
type: array
items:
type: string
example:
- LOCALE_BASED
- MMMM_D_YYYY
- MMM_D_YYYY
- D_MMM_YYYY
- YYYY_MM_DD_HYPHEN
- YYYY_MM_DD_DOT
- DWWWW_MMMM_D_YYYY
- DWWW_DD_MMM_YYYY
- DWWW_MM_DD_YYYY
- MMMM_D
- D_MMMM
decimalCount:
type: array
items:
type: string
example:
- '0'
- '1'
- '2'
- '3'
- '4'
- '5'
fontFamily:
type: array
items:
$ref: '#/components/schemas/FormatTables/properties/fontFamily/items'
example:
- name: Arial
traits:
- sans-serif
- name: Roboto
traits:
- sans-serif
- name: Tahoma
traits:
- sans-serif
- name: Times New Roman
traits:
- serif
- name: Verdana
traits:
- sans-serif
fontSize:
type: array
items:
type: string
example:
- '8'
- '9'
- '10'
- '12'
- '14'
- '16'
- '18'
- '20'
- '24'
- '28'
- '32'
- '36'
horizontalAlign:
description: The default setting is "default" which is equivalent to
"left".
type: array
items:
type: string
example:
- default
- left
- center
- right
italic:
type: array
items:
type: string
example:
- none
- on
numberFormat:
type: array
items:
type: string
example:
- none
- NUMBER
- CURRENCY
- PERCENT
strikethrough:
type: array
items:
type: string
example:
- none
- on
textWrap:
type: array
items:
type: string
example:
- none
- on
thousandsSeparator:
type: array
items:
type: string
example:
- none
- on
underline:
type: array
items:
type: string
example:
- none
- on
verticalAlign:
description: The default setting is "default" which is equivalent to
"top".
type: array
items:
type: string
example:
- default
- top
- middle
- bottom
supportedLocales:
description: Array of strings representing all Smartsheet-supported locales.
type: array
items:
type: string
Share:
type: object
properties:
id:
description: >
Share Id.
**NOTE**: unlike other Smartsheet object Ids, this Id is an alphanumeric
string.
type: string
groupId:
description: Group Id if the share is a group share, else null.
type: number
userId:
description: User Id if the share is a user share, else null.
type: number
type:
description: |
The type of this share. One of the following values: GROUP or USER.
type: string
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
ccMe:
description: >
Indicates whether to send a copy of the email to the sharer of the
sheet. You can specify this attribute
in a request, but it is never present in a response.
type: boolean
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
email:
description: User's primary email address for user shares; null for group
shares.
type: string
message:
description: >
The message included in the body of the email that is optionally
sent to the recipient. You can specify
this attribute in a request, but it is never present in a response.
type: string
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
name:
description: If a user share and user is also a contact, the user's full
name. If a group share, the group's name.
type: string
scope:
description: >
The scope of this share. One of the following values:
* **ITEM**: an item-level share (that is, the specific object to which
the share applies is shared with
the user or group).
* **WORKSPACE**: a workspace-level share (that is, the workspace that
contains the object to which the
share applies is shared with the user or group).
type: string
subject:
description: >
The subject of the email that is optionally sent to notify the
recipient. You can specify this attribute
in a request, but it is never present in a response.
type: string
SharedSecret:
type: object
properties:
sharedSecret:
description: Value for the shared secret.
type: string
Sheet:
type: object
properties:
id:
description: Sheet Id.
type: number
fromId:
description: The Id of the template from which to create the sheet. This
attribute can be specified in a request, but is never present in a response.
type: number
ownerId:
description: User Id of the sheet owner.
type: number
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
attachments:
description: >
Array of Attachment objects.
Only returned if the [include](../../tag/sheets#operation/getSheet) query
string parameter contains **attachments**.
type: array
items:
$ref: '#/components/schemas/Comment/properties/attachments/items'
columns:
type: array
items:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/columns/items'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
crossSheetReferences:
description: >
Array of CrossSheetReference objects.
Only returned if the [include](../../tag/sheets#operation/getSheet) query
string parameter contains **crossSheetReferences**.
type: array
items:
type: object
properties:
endColumnId:
description: Defines ending edge of range when specifying one or more
columns. To specify an entire column, omit the startRowId and endRowId
parameters.
type: number
endRowId:
description: Defines ending edge of range when specifying one or more
rows. To specify an entire row, omit the startColumnId and endColumnId
parameters.
type: number
id:
description: Cross-sheet reference Id, guaranteed unique within referencing
sheet.
type: number
name:
description: Friendly name of reference. Auto-generated unless specified
in Create Cross-sheet References.
type: string
startColumnId:
description: Defines beginning edge of range when specifying one or
more columns. To specify an entire column, omit the startRowId and
endRowId parameters.
type: number
startRowId:
description: Defines beginning edge of range when specifying one or
more rows. To specify an entire row, omit the startColumnId and
endColumnId parameters.
type: number
status:
description: >
Status of request:
* 'BLOCKED' - A reference is downstream of a circular issue.
* 'BROKEN' - The data source location (column, row or sheet) was
deleted.
* 'CIRCULAR' - The formula reference is self referencing and cannot
be resolved.
* 'DISABLED' - Updating the reference is temporarily disabled due
to maintenance.
* 'INVALID/UNKNOWN' - The reference is new and had not been validated.
* 'NOT_SHARED' - No common shared users.
* 'OK' - The reference is in a good state.
type: string
enum:
- BLOCKED
- BROKEN
- CIRCULAR
- DISABLED
- INVALID/UNKNOWN
- NOT-SHARED
- OK
sourceSheetId:
description: Sheet Id of source sheet.
type: number
dependenciesEnabled:
description: Indicates whether dependencies are enabled.
type: boolean
discussions:
description: >
Array of Discussion objects
Only returned if the [include](../../tag/sheets#operation/getSheet) query
string parameter contains **discussions**.
type: array
items:
$ref: '#/components/schemas/Proof/properties/discussions/items'
effectiveAttachmentOptions:
description: >
Array of enum strings (see
[Attachment.attachmentType](../../tag/attachmentsDescription)
indicating the allowable attachment options for the current user and
sheet.
type: array
items:
type: string
favorite:
description: Returned only if the user has marked this sheet as a favorite
in their Home tab (value = **true**).
type: boolean
ganttEnabled:
description: Indicates whether "Gantt View" is enabled.
type: boolean
hasSummaryFields:
description: Indicates whether a sheet summary is present.
type: boolean
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
name:
description: Sheet name.
type: string
owner:
description: Email address of the sheet owner.
type: string
permalink:
description: URL that represents a direct link to the sheet in Smartsheet.
type: string
projectSettings:
description: Represents the project settings dependencies for a specific
sheet. Project settings may be updated on sheets that the user has editor
access.
type: object
properties:
lengthOfDay:
description: Length of a workday for a project sheet.
type: number
minimum: 1
maximum: 24
nonWorkingDays:
description: Non-working days for a project sheet.
type: array
items:
type: string
format: date
workingDays:
type: array
items:
type: string
enum:
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
- SUNDAY
readOnly:
description: Returned only if the sheet belongs to an expired trial (value
= **true**).
type: boolean
resourceManagementEnabled:
description: Indicates that resource management is enabled.
type: boolean
rows:
type: array
items:
$ref: '#/components/schemas/ReportRow/allOf/0'
showParentRowsForFilters:
description: Returned only if there are column filters on the sheet. Value
= **true** if "show parent rows" is enabled for the filters.
type: boolean
source:
type: object
properties:
id:
description: >
The Id of the dashboard, report, sheet, or template from which
the enclosing dashboard, report, sheet, or template was created.
type: number
type:
description: >
**report**, **sheet**, **sight** (aka dashboard), or
**template**.
type: string
summary:
type: object
description: Represents the entire summary, or a list of defined fields
and values, for a specific sheet.
properties:
fields:
description: Array of summary (or metadata) fields defined on the sheet.
type: array
items:
$ref: '#/components/schemas/CellDataItem/properties/profileField'
totalRowCount:
description: The total number of rows in the sheet.
type: number
userPermissions:
type: object
description: Describes the current user's editing permissions for a specific
sheet.
properties:
summaryPermissions:
description: >
One of:
* ADMIN: full control over fields.
* READ_DELETE: sheet is owned by an individual account that doesn't
have summary capabilities. If a summary exists, the only possible
operations are GET and DELETE fields.
* READ_ONLY.
* READ_WRITE: can edit values of existing fields, but not create
or delete fields, nor modify field type.
type: string
enum:
- ADMIN
- READ_DELETE
- READ_ONLY
- READ_WRITE
userSettings:
type: object
description: Represents individual user settings for a specific sheet. User
settings may be updated even on sheets where the current user only has
read access (for example, viewer permissions or a read-only sheet).
properties:
criticalPathEnabled:
description: >
Does this user have "Show Critical Path" turned on for this
sheet? **NOTE**: This setting only has an effect on project
sheets with dependencies enabled.
type: boolean
displaySummaryTasks:
description: Does this user have "Display Summary Tasks" turned on for
this sheet? Applies only to sheets where "Calendar View" has been
configured.
type: boolean
version:
description: A number that is incremented every time a sheet is modified.
type: number
workspace:
$ref: '#/components/schemas/Home/properties/workspaces/items'
SheetEmail:
allOf:
- $ref: '#/components/schemas/ProofRequestBody/allOf/0'
type: object
properties:
format:
description: |
One of the following values: **EXCEL**, **PDF**, or **PDF_GANTT**.
type: string
formatDetails:
type: object
properties:
paperSize:
description: Specifies paper size.
type: string
example: LETTER
enum:
- A0
- A1
- A2
- A3
- A4
- ARCHID
- LEGAL
- LETTER
- WIDE
SheetPublish:
description: Describes the sheet's publish settings.
type: object
properties:
icalEnabled:
description: If **true**, a webcal is available for the calendar in the
sheet.
type: boolean
icalUrl:
description: >
URL for **iCal** view of the published sheet. Only returned in a
response if **icalEnabled = true**.
readOnlyFullAccessibleBy:
description: >
Indicates who can access the 'Read-Only Full' view of the published
sheet:
* ALL - available to anyone who has the link.
* ORG - available only to members of the sheet owner's Smartsheet organization
account.
* SHARED - available only to users shared to the item.
Only returned in the response if **readOnlyFullEnabled = true**.
type: string
enum:
- ALL
- ORG
- SHARED
readOnlyFullDefaultView:
description: >
Indicates which view the user has set for a read-only, default view
of the published sheet. Must be one of the listed enum values.
type: string
enum:
- CALENDAR
- CARD
- GRID
readOnlyFullEnabled:
description: If **true**, a rich version of the sheet is published with
the ability to download row attachments and discussions.
type: boolean
readOnlyFullShowToolbar:
description: Indicates whether the left nav toolbar is displayed. The default,
or **true**, is to display the toolbar. If **false**, hides the toolbar.
type: boolean
deprecated: true
readOnlyFullUrl:
description: URL for 'Read-Only Full' view of the published sheet. Only
returned in a response if **readOnlyFullEnabled = true.
type: string
readOnlyLiteEnabled:
description: If **true**, a lightweight version of the sheet is published
without row attachments and discussions.
type: boolean
readOnlyLiteSslUrl:
description: URL for 'Read-Only' view of the published sheet when SSL is
enabled.
type: string
readOnlyLiteUrl:
description: URL for 'Read-Only HTML' view of the published sheet. Only
returned in a response if **readOnlyLiteEnabled = true**.
type: string
readWriteAccessibleBy:
description: >
Indicates who can access the 'Edit by Anyone' view of the published
sheet:
* ALL - available to anyone who has the link.
* ORG - available only to members of the sheet owner's Smartsheet organization
account.
* SHARED - available only to users shared to the item.
Only returned in the response if **readWriteEnabled = true**.
type: string
enum:
- ALL
- ORG
- SHARED
readWriteDefaultView:
description: >
Indicates which view the user has set for a read-write, default view
of the published sheet. Must be one of the listed enum values.
type: string
enum:
- CALENDAR
- CARD
- GRID
readWriteEnabled:
description: If **true**,a rich version of the sheet is published with the
ability to edit cells and manage attachments and discussions.
type: boolean
readWriteShowToolbar:
description: Indicates whether the left nav toolbar is displayed. The default,
or **true**, is to display the toolbar. If **false**, hides the toolbar.
type: boolean
deprecated: true
readWriteUrl:
description: URL for 'Edit by Anyone' view of the published sheet. Only
returned in a response if **readWriteEnabled = true**.
type: string
SheetSummary:
type: object
description: Represents the entire summary, or a list of defined fields and
values, for a specific sheet.
properties:
fields:
description: Array of summary (or metadata) fields defined on the sheet.
type: array
items:
$ref: '#/components/schemas/CellDataItem/properties/profileField'
SheetUserPermissions:
type: object
description: Describes the current user's editing permissions for a specific
sheet.
properties:
summaryPermissions:
description: >
One of:
* ADMIN: full control over fields.
* READ_DELETE: sheet is owned by an individual account that doesn't
have summary capabilities. If a summary exists, the only possible operations
are GET and DELETE fields.
* READ_ONLY.
* READ_WRITE: can edit values of existing fields, but not create or
delete fields, nor modify field type.
type: string
enum:
- ADMIN
- READ_DELETE
- READ_ONLY
- READ_WRITE
SheetUserSettings:
type: object
description: Represents individual user settings for a specific sheet. User
settings may be updated even on sheets where the current user only has read
access (for example, viewer permissions or a read-only sheet).
properties:
criticalPathEnabled:
description: >
Does this user have "Show Critical Path" turned on for this sheet?
**NOTE**: This setting only has an effect on project sheets with
dependencies enabled.
type: boolean
displaySummaryTasks:
description: Does this user have "Display Summary Tasks" turned on for this
sheet? Applies only to sheets where "Calendar View" has been configured.
type: boolean
ShortcutDataItem:
type: object
properties:
attachmentType:
type: string
enum:
- BOX_COM
- DROPBOX
- EGNYTE
- EVERNOTE
- FILE
- GOOGLE_DRIVE
- LINK
- ONEDRIVE
- SMARTSHEET
hyperlink:
$ref: '#/components/schemas/Cell/properties/hyperlink'
label:
description: Label for the data point.
type: string
labelFormat:
description: Format description of label.
type: string
example: ',,1,1,,,,,,,,,,,,,'
mimeType:
type: string
order:
description: The display order for the ShortcutWidgetItem object.
type: number
ShortcutWidgetContent:
type: object
title: Shortcut
properties:
type:
type: string
enum:
- SHORTCUT
- SHORTCUTICON
- SHORTCUTLIST
shortcutData:
type: array
items:
type: object
properties:
attachmentType:
type: string
enum:
- BOX_COM
- DROPBOX
- EGNYTE
- EVERNOTE
- FILE
- GOOGLE_DRIVE
- LINK
- ONEDRIVE
- SMARTSHEET
hyperlink:
$ref: '#/components/schemas/Cell/properties/hyperlink'
label:
description: Label for the data point.
type: string
labelFormat:
description: Format description of label.
type: string
example: ',,1,1,,,,,,,,,,,,,'
mimeType:
type: string
order:
description: The display order for the ShortcutWidgetItem object.
type: number
Sight:
type: object
allOf:
- type: object
allOf:
- type: object
allOf:
- type: object
properties:
name:
description: Dashboard name.
type: string
properties:
id:
description: Dashboard Id.
type: number
readOnly: true
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
permalink:
description: URL that represents a direct link to the dashboard in Smartsheet.
type: string
readOnly: true
properties:
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
properties:
backgroundColor:
description: The hex color, for instance `#E6F5FE`.
type: string
readOnly: true
columnCount:
description: Number of columns that the dashboard contains.
type: number
readOnly: true
favorite:
description: Indicates whether the user has marked the dashboard as a favorite.
type: boolean
readOnly: true
source:
$ref: '#/components/schemas/Sheet/properties/source'
widgets:
readOnly: true
type: array
items:
type: object
readOnly: true
properties:
id:
description: Widget Id.
type: number
type:
description: Type of widget.
type: string
enum:
- CHART
- GRIDGANTT
- IMAGE
- METRIC
- RICHTEXT
- SHEETSUMMARY
- SHORTCUT
- SHORTCUTICON
- SHORTCUTLIST
- TITLE
- WEBCONTENT
contents:
description: The type of widget content depends on the value of widget.type.
oneOf:
- $ref: '#/components/schemas/Widget/properties/contents/oneOf/0'
- $ref: '#/components/schemas/Widget/properties/contents/oneOf/1'
- $ref: '#/components/schemas/Widget/properties/contents/oneOf/2'
- $ref: '#/components/schemas/Widget/properties/contents/oneOf/3'
- $ref: '#/components/schemas/Widget/properties/contents/oneOf/4'
- $ref: '#/components/schemas/Widget/properties/contents/oneOf/5'
- $ref: '#/components/schemas/Widget/properties/contents/oneOf/6'
- $ref: '#/components/schemas/Widget/properties/contents/oneOf/7'
height:
description: Number of rows that the widget occupies on the dashboard.
type: number
showTitle:
description: True indicates that the client should display the widget
title. This is independent of the title string which may be null
or empty.
type: boolean
showTitleIcon:
description: True indicates that the client should display the sheet
icon in the widget title.
type: boolean
title:
description: Title of the widget.
type: string
titleFormat:
description: Title format descriptor (see [Formatting](../#section/API-Basics/Formatting)).
type: string
example: ',,1,,,,,,,3,,,,,,1,'
version:
description: Widget version number.
type: number
viewMode:
description: >
Indicates the content layout. Must use a query parameter of
level=2 to see this information.
* 1 - centered
* 2 - left aligned
type: number
enum:
- 1
- 2
width:
description: Number of columns that the widget occupies on the dashboard.
type: number
xPosition:
description: X-coordinate of widget's position on the dashboard.
type: number
yPosition:
description: Y-coordinate of widget's position on the dashboard.
type: number
workspace:
$ref: '#/components/schemas/Home/properties/workspaces/items'
SightPublish:
description: Describes the dashboard's publish settings.
type: object
properties:
readOnlyFullAccessibleBy:
description: >
Indicates who can access the 'Read-Only Full' view of the published
dashboard. Only returned in the response if **readOnlyFullEnabled =
true**.
* **ALL** - available to anyone who has the link.
* **ORG** - available only to members of the dashboard owner's Smartsheet
organization account.
* **SHARED** - available only to users shared to the item.
---
If **readOnlyFullEnabled** is set to true in the request, but **readOnlyFullAccessibleBy**
is not specified, the value of **readOnlyFullAccessibleBy** defaults to
the organization-level 'Dashboard Publishing' setting (if the dashboard
owner belongs to an organization account) or to **ALL** (if the dashboard
owner does not belong to an organization account).
type: string
enum:
- ALL
- ORG
readOnlyFullEnabled:
description: If true, a rich version of the dashboard is published with
the ability to use shortcuts and widget interactions.
type: boolean
readOnlyFullUrl:
description: URL for 'Read-Only Full' view of the published dashboard. Only
returned in a response if readOnlyFullEnabled = true.
type: string
readOnly: true
required:
- readOnlyFullEnabled
SortCriterion:
type: object
properties:
columnId:
type: number
direction:
description: Direction of the sort.
type: string
enum:
- ASCENDING
- DESCENDING
default: ASCENDING
SortSpecifier:
type: object
properties:
sortCriteria:
description: Specifies sort order. Array is in priority order.
type: array
items:
type: object
properties:
columnId:
type: number
direction:
description: Direction of the sort.
type: string
enum:
- ASCENDING
- DESCENDING
default: ASCENDING
Source:
type: object
properties:
id:
description: >
The Id of the dashboard, report, sheet, or template from which the
enclosing dashboard, report, sheet, or template was created.
type: number
type:
description: |
**report**, **sheet**, **sight** (aka dashboard), or **template**.
type: string
StreamResult:
description: StreamResult Object
type: object
properties:
nextStreamPosition:
description: This string should be passed back to the next GET events call
to obtain subsequent events.
type: string
example: XyzAb1234cdefghijklmnofpq
moreAvailable:
description: True if more results are available. This is typically due to
event counts exceeding the maxCount parameter passed in.
type: boolean
example: true
SummaryField:
type: object
properties:
id:
description: SummaryField Id.
type: number
contactOptions:
description: Array of ContactOption objects to specify a pre-defined list
of values for the column. Column type must be CONTACT_LIST.
type: array
items:
$ref: '#/components/schemas/Column/properties/contactOptions/items'
createdAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
createdBy:
description: User object containing name and email of the creator of this
summary field.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
displayValue:
description: Visual representation of cell contents, as presented to the
user in the UI.
type: string
format:
description: The format descriptor. Only returned if the include query string
parameter contains format and this column has a non-default format applied
to it.
type: string
formula:
description: The formula for a cell, if set.
type: string
hyperlink:
$ref: '#/components/schemas/Cell/properties/hyperlink'
image:
$ref: '#/components/schemas/Cell/properties/image'
index:
description: Field index or position. This number is zero-based.
type: number
locked:
description: Indicates whether the field is locked.
type: boolean
lockedForUser:
description: Indicates whether the field is locked for the requesting user.
type: boolean
modifiedAt:
$ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedBy:
description: User object containing name and email of the user who most
recently modified this summary field.
type: object
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
objectValue:
$ref: '#/components/schemas/Cell/properties/objectValue'
options:
description: When applicable for PICKLIST column type. Array of the options
available for the field.
type: array
items:
type: string
symbol:
description: When applicable for PICKLIST column type.
type: string
title:
description: Arbitrary name, must be unique within summary.
type: string
type:
type: string
enum:
- ABSTRACT_DATETIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATETIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
validation:
description: Indicates whether summary field values are restricted to the
type.
type: boolean
Template:
description: A template can be used to create a sheet.
type: object
properties:
id:
description: Template Id.
type: number
type:
description: Type of template. Only applicable to public templates.
type: string
enum:
- report
- sheet
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
blank:
description: Indicates whether the template is blank. Only applicable to
public templates.
type: boolean
categories:
description: Indicates whether the template is blank. Only applicable to
public templates.
type: array
items:
type: string
description:
description: Template description.
type: string
globalTemplate:
description: Type of global template. Only applicable to blank public templates.
type: string
enum:
- BLANK_SHEET
- PROJECT_SHEET
- TASK_LIST
image:
description: URL to the small preview image for this template. Only applicable
to non-blank public templates.
type: string
largeImage:
description: URL to the large preview image for this template. Only applicable
to non-blank public templates.
type: string
locale:
description: Locale of the template. Only applicable to public templates.
type: string
enum:
- ar_AE
- ar_BH
- ar_DZ
- ar_EG
- ar_IQ
- ar_JO
- ar_KW
- ar_LB
- ar_LY
- ar_MA
- ar_OM
- ar_QA
- ar_SA
- ar_SD
- ar_SY
- ar_TN
- ar_YE
- be_BY
- bg_BG
- ca_ES
- cs_CZ
- da_DK
- de_AT
- de_CH
- de_DE
- de_LU
- el_CY
- el_GR
- en_AU
- en_CA
- en_GB
- en_IE
- en_IN
- en_MT
- en_NZ
- en_PH
- en_SG
- en_US
- en_ZA
- es_AR
- es_BO
- es_CL
- es_CO
- es_CR
- es_DO
- es_EC
- es_ES
- es_GT
- es_HN
- es_MX
- es_NI
- es_PA
- es_PE
- es_PR
- es_PY
- es_SV
- es_US
- es_UY
- es_VE
- et_EE
- fi_FI
- fr_BE
- fr_CA
- fr_CH
- fr_FR
- fr_LU
- ga_IE
- hi_US
- hr_HR
- hu_HU
- in_ID
- is_IS
- it_CH
- it_IT
- iw_IL
- ja_JP
- ko_KR
- lt_LT
- lv_LV
- mk_MK
- ms_MY
- mt_MT
- nl_BE
- nl_NL
- no_NO
- pl_PL
- pt_BR
- pt_PT
- ro_RO
- ru_RU
- sk_SK
- sl_SI
- sq_AL
- sr_BA
- sr_CS
- sv_SE
- th_US
- tr_TR
- uk_UA
- vi_VN
- zh_CN
- zh_HK
- zh_SG
- zh_TW
name:
type: string
description: Type of global template.
example: Awesome Project Template
tags:
description: List of search tags for this template. Only applicable to non-blank
public templates.
type: array
items:
type: string
Timestamp:
oneOf:
- type: string
format: date-time
- type: number
readOnly: true
TitleWidgetContent:
type: object
title: Title
properties:
type:
type: string
enum:
- TITLE
backgroundColor:
type: string
htmlContent:
type: string
description: >
The widget contents as HTML. The Title widget supports the following
subset of HTML tags and CSS Styles:
HTML
* br - line break
* p - paragraph
* span - section of the document
CSS
* color
* font-family
* font-size
* font-style
* font-weight
* text-align
* text-decoration
example: HI!
Token:
type: object
properties:
access_token:
description: A credential that can be used by a client to access the Smartsheet
API.
type: string
readOnly: true
token_type:
description: How an access token will be generated and presented. Smartsheet
uses the bearer parameter, which means essentially give access to the
bearer of this token.
type: string
readOnly: true
expires_in:
description: Number of seconds token is valid once issued.
type: number
default: 604799
readOnly: true
refresh_token:
description: A credential tied to the access token that can be used to obtain
a fresh access token with the same permissions, without further involvement
from a user.
type: string
readOnly: true
UpdateProofStatusRequest:
type: object
properties:
isCompleted:
type: boolean
UpdateRequest:
type: object
allOf:
- allOf:
- $ref: '#/components/schemas/MultiRowEmail/allOf/0'
type: object
properties:
rowIds:
description: The Ids of rows to be included.
type: array
items:
type: number
- type: object
properties:
id:
description: Id of the update request.
type: number
createdAt:
description: The date and time for when this request was originally created.
Read-only.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
modifiedAt:
description: The date and time for when the last change was made to this
request. Read-only.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
schedule:
description: The schedule for which update requests are sent out.
allOf:
- type: object
properties:
type:
description: Type of schedule.
type: string
enum:
- ONCE
- DAILY
- WEEKLY
- MONTHLY
- YEARLY
dayDescriptors:
description: >
A string array consists of one or more of the following
values:
* **DAY**, **WEEKDAY**, **WEEKEND**
* **SUNDAY**, **MONDAY**, **TUESDAY**, **WEDNESDAY**, **THURSDAY**,
**FRIDAY**, **SATURDAY**
The subset of values applicable to the schedule type are as followed:
| Value | Daily schedule | Weekly schedule | Monthly schedule
|
|---------------|----------------|-----------------|------------------|
| **DAY** | | | **✓** |
| **WEEKDAY** | **✓** | | **✓** |
| **WEEKEND** | | | **✓** |
| **SUNDAY** | | **✓** | **✓** |
| **MONDAY** | | **✓** | **✓** |
| **TUESDAY** | | **✓** | **✓** |
| **WEDNESDAY** | | **✓** | **✓** |
| **THURSDAY** | | **✓** | **✓** |
| **FRIDAY** | | **✓** | **✓** |
| **SATURDAY** | | **✓** | **✓** |
For more details, refer to the Table of Schedule Object’s Attributes
below.
type: array
items:
type: string
enum:
- DAY
- WEEKDAY
- WEEKEND
- SUNDAY
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
dayOfMonth:
description: >
The day within the month.
Valid range is 1 to 28.
This attribute is applicable to the following schedule type:
* **MONTHLY**
For more details, refer to the Table of Schedule Object’s Attributes
below.
type: number
minimum: 1
maximum: 31
dayOrdinal:
description: >
Must be one of the following values:
* **FIRST** or **LAST**
* **SECOND**, **THIRD**, or **FOURTH**
This attribute is applicable to the following schedule type:
* **MONTHLY**
For more details, refer to the Table of Schedule Object’s Attributes
below.
type: string
enum:
- FIRST
- LAST
- SECOND
- THIRD
- FOURTH
repeatEvery:
description: >
Frequency on which the request is delivered. The unit is
a function of the **type** attribute. For example,
for **MONTHLY** schedule, **repeatEvery=1** means every month.
Valid range is 1 to 99.
This attribute is applicable to the following schedule types:
**DAILY**, **WEEKLY**, **MONTHLY**, or **YEARLY**.
For more details, refer to the Table of Schedule Object’s Attributes
below.
type: number
minimum: 1
maximum: 99
endAt:
allOf:
- description: >
The date, time, and time zone at which the delivery
schedule ends.
The value is either in a string format or a numeric format:
* When the value is a string, it must be a valid ISO-8601 date
and time with an offset (YYYY-MM-DDThh:mm:ssTZD).
* When the value is a number, it represents a date and time
with no offset (UTC time zone). See Dates and Times for more
information.
The value must be later than startAt and the current date and
time.
The value must contain zero hours, zero minutes, and zero seconds.
The offset (time zone) value must be the same as the offset
(time zone) value in startAt.
This attribute is applicable to the following schedule types:
DAILY, WEEKLY, MONTHLY, YEARLY. For more details, refer to the
Table of Schedule Object’s Attributes below.
- $ref: '#/components/schemas/Schedule/properties/endAt/allOf/1'
lastSentAt:
allOf:
- description: The date and time for when the last request was sent.
- $ref: '#/components/schemas/Attachment/properties/createdAt'
nextSendAt:
allOf:
- description: The date and time for when the next request is scheduled
to send.
- $ref: '#/components/schemas/Attachment/properties/createdAt'
startAt:
allOf:
- description: >
The date, time, and time zone at which the first
delivery starts.
The value is either in a string format or a numeric format:
* When the value is a string, it must be a valid ISO-8601
date and time with an offset (YYYY-MM-DDThh:mm:ssTZD).
* When the value is a number, it represents a date and time
with no offset (UTC time zone). See [Dates and Times](../../#section/API-Basics/Dates-and-Times)
for more information.
For ONCE schedule type, it must be later than the current date
time.
For all other schedule types, it must be later than “2000-01-01T00:00:00Z”
in string format or 946684800000 in numeric format.
The value must contain zero minutes and zero seconds.
This attribute is applicable to all schedule types.
For more details, refer to the Table of Schedule Object’s Attributes
below.
- $ref: '#/components/schemas/Schedule/properties/endAt/allOf/1'
sentBy:
description: |
`User` object containing `name` and `email` of the sender.
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdBy/allOf/0'
URLAttachmentRequest:
type: object
properties:
attachmentSubType:
description: Attachment sub type. * type is for EGNYTE values and the rest
are GOOGLE_DRIVE values.
type: string
enum:
- DOCUMENT
- DRAWING
- FOLDER*
- PDF
- PRESENTATION
- SPREADSHEET
attachmentType:
description: Attachment type. * types are not supported for Smartsheet.gov
accounts.
type: string
enum:
- BOX_COM
- DROPBOX*
- EGNYTE*
- EVERNOTE*
- FILE
- GOOGLE_DRIVE
- LINK
- ONEDRIVE
description:
type: string
name:
type: string
url:
type: string
User:
description: User Object
type: object
properties:
id:
description: User Id.
type: number
readOnly: true
example: 48569348493401200
admin:
description: Indicates whether the user is a system admin (can manage user
accounts and organization account).
type: boolean
default: false
example: true
customWelcomeScreenViewed:
description: Timestamp of viewing an [Enterprise Custom Welcome Screen](https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only)
by the current user.
type: string
format: date-time
readOnly: true
example: 2020-08-25T12:15:47Z
email:
description: User's primary email address.
type: string
format: email
example: jane.doe@smartsheet.com
firstName:
description: User's first name.
type: string
example: Jane
groupAdmin:
description: Indicates whether the user is a group admin (can create and
edit groups).
type: boolean
default: false
example: true
lastLogin:
description: Last login time of the current user.
type: string
format: date-time
readOnly: true
example: 2020-10-04T18:32:47Z
lastName:
description: User's last name.
type: string
example: Doe
licensedSheetCreator:
description: Indicates whether the user is a licensed user (can create and
own sheets).
type: boolean
default: false
example: true
name:
description: User's full name (read-only).
type: string
readOnly: true
example: Jane Doe
profileImage:
type: object
properties:
imageId:
description: Unique image Id.
type: string
example: u!1!nAtdn5RJB_o!k6_e_3h2R3w!wmYXPek-yVD
height:
description: Image height.
type: string
example: 1050
width:
description: Image width.
type: string
example: 1050
resourceViewer:
description: Indicates whether the user is a resource viewer (can access
resource views).
type: boolean
default: false
example: true
sheetCount:
description: The number of sheets owned by the current user within the organization
account.
type: number
readOnly: true
example: 42
status:
description: User status, set to one of the listed enum values.
type: string
enum:
- ACTIVE
- DECLINED
- PENDING
example: ACTIVE
UserProfile:
type: object
properties:
id:
description: Current user's Id.
type: number
example: 48569348493401200
account:
type: object
properties:
id:
description: Account Id.
type: number
example: 122454719915908
name:
description: Account name.
type: string
example: Smartsheet Org
admin:
description: Indicates whether the user is a system admin (can manage user
accounts and organization account).
type: boolean
example: true
alternateEmails:
type: object
properties:
id:
description: AlternateEmail Id.
type: number
example: 8150532427671428
confirmed:
description: Indicates whether the alternate email address has been
confirmed.
type: boolean
example: true
email:
description: User's alternate email address.
type: string
example: johnathan.doe@smartsheet.com
company:
description: User's company.
type: string
example: Smartsheet
customWelcomeScreenViewed:
description: Timestamp of viewing an [Enterprise Custom Welcome Screen](https://help.smartsheet.com/articles/1392225-customizing-a-welcome-message-upgrade-screen-enterprise-only)
by the current user.
type: string
format: date-time
example: 2020-08-25T12:15:47Z
department:
description: User's department.
type: string
example: Engineering
email:
description: Current user's primary email address.
type: string
example: john.doe@smartsheet.com
firstName:
description: Current user's first name.
type: string
example: John
groupAdmin:
description: Indicates whether the user is a group admin (can create and
edit groups).
type: boolean
example: true
jiraAdmin:
description: Indicates whether the user is a JIRA admin.
type: boolean
example: true
lastLogin:
description: Last login time of the current user.
type: string
format: date-time
example: 2020-10-31T12:15:47Z
lastName:
description: Current user's last name.
type: string
example: Doe
licensedSheetCreator:
description: Indicates whether the user is a licensed user (can create and
own sheets).
type: boolean
example: true
locale:
description: Current user's locale (see [Server Information](../../tag/serverInfoObjects#section/Server-Info-Object)).
type: string
example: en_US
mobilePhone:
description: User's mobile phone number.
type: string
example: 555-867-5309
profileImage:
$ref: '#/components/schemas/User/properties/profileImage'
resourceViewer:
description: Indicates whether the user is a resource viewer (can access
resource views).
type: boolean
example: true
role:
description: User's role.
type: string
example: Software Developer
salesforceAdmin:
description: Indicates whether the user is a Salesforce admin.
type: boolean
example: false
salesforceUser:
description: Indicates whether the user is a registered Salesforce user.
type: boolean
example: false
sheetCount:
description: The number of sheets owned by the current user within the organization
account.
type: number
example: 42
timeZone:
description: Current user's time zone Id.
type: string
example: US/Pacific
title:
description: User's title.
type: string
example: Senior Software Engineer
workPhone:
description: User's work phone number.
type: string
example: 844-324-2360
WebContentWidgetContent:
type: object
title: Web Content
properties:
type:
type: string
enum:
- WEBCONTENT
url:
description: The URL for the web content.
type: string
example: https://www.youtube.com/embed/quGpnXiCUms
Webhook:
allOf:
- type: object
properties:
callbackUrl:
description: HTTPS URL where callbacks are sent.
type: string
example: https://www.myApp.com/webhooks
enabled:
description: Indicates whether the webhook is on (true) or off (false).
ReadOnly for POST commands.
type: boolean
example: true
events:
description: Array of the events that are subscribed to. Currently, must
be an array of size 1 that contains the string value '\*.\*' (asterisk
period asterisk), which means "all objects" and "all events".
type: array
items:
type: string
example: '*.*'
name:
description: Webhook name.
type: string
example: Webhook for Sheet Creation
version:
description: Webhook version. Currently, the only supported value is 1.
This attribute is intended to ensure backward compatibility as new webhook
functionality is released. For example, a webhook with a version of
1 is guaranteed to always be sent callback objects that are compatible
with the version 1 release of webhooks.
type: number
example: 1
minimum: 1
maximum: 1
- type: object
properties:
id:
description: Webhook Id.
type: number
readOnly: true
example: 8444254503626628
apiClientId:
type: string
description: API client Id corresponding to third-party app that created
the webhook. Read-only. Only present if webhook was created by third-party
app.
readOnly: true
example: 555555
scopeObjectId:
type: number
description: Id of the object that is subscribed to. Specified when a
webhook is created and cannot be changed.
example: 3285357287499652
apiClientName:
type: string
description: API client name corresponding to third-party app that created
the webhook. Read-only. Only present if webhook was created by third-party
app.
readOnly: true
example: Awesome Smartsheet Application
createdAt:
readOnly: true
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
disabledDetails:
description: Details about the reason the webhook was disabled. Read-only.
Only present when enabled=false.
type: string
readOnly: true
modifiedAt:
readOnly: true
allOf:
- $ref: '#/components/schemas/Attachment/properties/createdAt'
scope:
description: Scope of the subscription. Currently, the only supported
value is sheet. Specified when a webhook is created and cannot be changed.
type: string
example: sheet
sharedSecret:
description: Shared secret for this Webhook, randomly generated by Smartsheet.
Read-only. See [Authenticating Callbacks](../../tag/webhooksDescription#section/Webhook-Callbacks/Authenticating-Callbacks-(optional))
for details about how this value can be used.
type: string
readOnly: true
example: 216ejjzdnq17mq1q8xs7d4hu8b
stats:
type: object
readOnly: true
properties:
lastCallbackAttempt:
type: string
format: date-time
readOnly: true
description: When this webhook last made a callback attempt.
lastCallbackAttemptRetryCount:
type: number
readOnly: true
description: The number of retries the webhook had performed as of
the last callback attempt.
lastSuccessfulCallback:
type: string
format: date-time
readOnly: true
description: When this webhook last made a successful callback.
status:
description: Webhook status. Read-only. See Webhook Status for list of
possible values.
type: string
readOnly: true
enum:
- DISABLED_ADMINISTRATIVE
- DISABLED_APP_REVOKED
- DISABLED_BY_OWNER
- DISABLED_CALLBACK_FAILED
- DISABLED_SCOPE_INACCESSIBLE
- DISABLED_VERIFICATION_FAILED
- ENABLED
- NEW_NOT_VERIFIED
example: ENABLED
subscope:
description: Array of column Ids if you want to limit the subscription
to a subscope. Specified when a webhook is created and cannot be changed.
type: array
items:
type: number
example:
columnIds:
- 7960873114331012
- 8731310160793142
Widget:
type: object
readOnly: true
properties:
id:
description: Widget Id.
type: number
type:
description: Type of widget.
type: string
enum:
- CHART
- GRIDGANTT
- IMAGE
- METRIC
- RICHTEXT
- SHEETSUMMARY
- SHORTCUT
- SHORTCUTICON
- SHORTCUTLIST
- TITLE
- WEBCONTENT
contents:
description: The type of widget content depends on the value of widget.type.
oneOf:
- type: object
title: Chart
properties:
type:
type: string
enum:
- CHART
reportId:
description: Report Id denoting container source, if applicable.
type: number
sheetId:
description: Sheet Id denoting container source, if applicable.
type: number
axes:
type: array
items:
type: object
properties:
location:
description: Describes location of the axis.
type: string
enum:
- BOTTOM
- LEFT
- NONE
- RIGHT
- TOP
title:
description: Axis title.
type: string
titleInfo:
type: object
properties:
type:
type: string
enum:
- ABSTRACT_DATE_TIME
- CHECKBOX
- CONTACT_LIST
- DATE
- DATE_TIME
- DURATION
- MULTI_CONTACT_LIST
- MULTI_PICKLIST
- PICKLIST
- PREDECESSOR
- TEXT_NUMBER
axisLabelFormat:
description: Describes the axis format (see [Formatting](/section/Formatting)).
type: string
example: ',,,,,,,,36,,,,,,,,'
includeZero:
description: Includes 0 in the axis.
type: boolean
hyperlink:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/hyperlink'
includedColumnIds:
description: Array of column Ids if the range was selected through
the UI.
type: array
items:
type: number
legend:
type: object
properties:
location:
type: string
enum:
- BOTTOM
- LEFT
- NONE
- RIGHT
- TOP
legendFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the legend has a non-default format applied
to it.
example: ',,1,1,,,,,,,,,,,,,'
selectionRanges:
type: array
items:
$ref: '#/components/schemas/ChartWidgetContent/properties/selectionRanges/items'
series:
type: array
items:
type: object
properties:
title:
type: string
titleInfo:
$ref: '#/components/schemas/Widget/properties/contents/oneOf/0/properties/axes/items/properties/titleInfo'
seriesTitleFormat:
type: string
description: Series title format (see [Formatting](/section/Formatting)).
seriesType:
type: string
enum:
- AREA
- BAR
- COLUMN
- LINE
- PIE
- SCATTER
dataLabels:
type: object
properties:
labelType:
type: string
enum:
- NONE
- PERCENT
- VALUE
tooltips:
type: object
properties:
labelType:
type: string
enum:
- NONE
- PERCENT
- X_SERIES_Y
- X_Y_PERCENT
- Y
- Y_PERCENT
lineType:
type: string
enum:
- CURVED
- STEPPED
- STRAIGHT
holeSize:
type: number
isFilled:
type: boolean
isHalf:
type: boolean
isStacked:
type: boolean
xFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the series has a non-default format applied
to it.
example: ',,1,1,,,,,,,,,,,,,'
yFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the series has a non-default format applied
to it.
example: ',,1,1,,,,,,,,,,,,,'
color:
type: string
axisLocationX:
type: string
enum:
- BOTTOM
- LEFT
- NONE
- RIGHT
- TOP
axisLocationY:
type: string
enum:
- BOTTOM
- LEFT
- NONE
- RIGHT
- TOP
yColumnInfo:
$ref: '#/components/schemas/Widget/properties/contents/oneOf/0/properties/axes/items/properties/titleInfo'
xColumnInfo:
$ref: '#/components/schemas/Widget/properties/contents/oneOf/0/properties/axes/items/properties/titleInfo'
seriesSelectionOrder:
type: string
enum:
- COLUMNS
- ROWS
seriesData:
type: array
items:
type: object
properties:
x:
type: number
y:
type: number
xFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the series has a non-default format
applied to it.
example: ',,1,1,,,,,,,,,,,,,'
yFormat:
type: string
description: The format descriptor (see [Formatting](/section/Formatting)).
Only returned if the series has a non-default format
applied to it.
example: ',,1,1,,,,,,,,,,,,,'
color:
type: string
selectionRanges:
type: array
items:
$ref: '#/components/schemas/ChartWidgetContent/properties/selectionRanges/items'
verticalGridLines:
type: object
properties:
lineStyle:
type: string
enum:
- SOLID
horizontalGridLines:
$ref: '#/components/schemas/Widget/properties/contents/oneOf/0/properties/verticalGridLines'
- type: object
title: Metric
properties:
type:
type: string
enum:
- METRIC
- SHEETSUMMARY
sheetId:
description: Sheet Id from which the cell data originates.
type: number
cellData:
type: array
items:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/cellData/items'
columns:
type: array
items:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/columns/items'
hyperlink:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/hyperlink'
- type: object
title: Image
properties:
type:
type: string
enum:
- IMAGE
privateId:
description: The image private Id.
type: string
fileName:
description: Name of the image file.
type: string
format:
description: Format descriptor. Follows the pattern in FormatTables.
type: string
example: ',7,1,,,,2,2,1,3,,,,,,1,'
height:
type: number
hyperlink:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/hyperlink'
width:
description: Original width of the image in pixels.
type: number
- type: object
title: Report
properties:
type:
type: string
enum:
- GRIDGANTT
reportId:
description: Report Id denoting container source.
type: number
htmlContent:
description: HTMl snippet to render report.
type: string
backgroundColor:
description: The hex color.
example: '#E6F5FE'
type: string
hyperlink:
$ref: '#/components/schemas/CellLinkWidgetContent/properties/hyperlink'
- type: object
title: Rich Text
properties:
type:
type: string
enum:
- RICHTEXT
htmlContent:
description: >
The widget contents as HTML. The Rich Text widget supports
the following subset of HTML tags and CSS Styles:
HTML
* a - hyperlink
* br - line break
* li - list item
* ol - ordered list
* p - paragraph
* span - section of the document
* ul - unordered list
CSS
* color
* font-family
* font-size
* font-style
* font-weight
* text-align
* text-decoration
type: string
- type: object
title: Shortcut
properties:
type:
type: string
enum:
- SHORTCUT
- SHORTCUTICON
- SHORTCUTLIST
shortcutData:
type: array
items:
$ref: '#/components/schemas/ShortcutWidgetContent/properties/shortcutData/items'
- type: object
title: Title
properties:
type:
type: string
enum:
- TITLE
backgroundColor:
type: string
htmlContent:
type: string
description: >
The widget contents as HTML. The Title widget supports the
following subset of HTML tags and CSS Styles:
HTML
* br - line break
* p - paragraph
* span - section of the document
CSS
* color
* font-family
* font-size
* font-style
* font-weight
* text-align
* text-decoration
example: HI!
- type: object
title: Web Content
properties:
type:
type: string
enum:
- WEBCONTENT
url:
description: The URL for the web content.
type: string
example: https://www.youtube.com/embed/quGpnXiCUms
height:
description: Number of rows that the widget occupies on the dashboard.
type: number
showTitle:
description: True indicates that the client should display the widget title.
This is independent of the title string which may be null or empty.
type: boolean
showTitleIcon:
description: True indicates that the client should display the sheet icon
in the widget title.
type: boolean
title:
description: Title of the widget.
type: string
titleFormat:
description: Title format descriptor (see [Formatting](../#section/API-Basics/Formatting)).
type: string
example: ',,1,,,,,,,3,,,,,,1,'
version:
description: Widget version number.
type: number
viewMode:
description: >
Indicates the content layout. Must use a query parameter of level=2
to see this information.
* 1 - centered
* 2 - left aligned
type: number
enum:
- 1
- 2
width:
description: Number of columns that the widget occupies on the dashboard.
type: number
xPosition:
description: X-coordinate of widget's position on the dashboard.
type: number
yPosition:
description: Y-coordinate of widget's position on the dashboard.
type: number
WidgetHyperlink:
type: object
properties:
interactionType:
description: >
Specifies what happens when a user clicks the widget. The type will
determine what other properties are needed.
* DISTI_COPY - a distribution link, only available if org has distribution
links enabled.
* NONE - do nothing, no other attribute required.
* SMARTSHEET_ITEM - open a Smartsheet item that is not the SOURCE_SHEET,
must also have one of the following attributes:
* dashboardId
* folderId
* reportId
* sheetId
* workspaceId
* SOURCE_SHEET - open the container where the widget data comes from,
no other attribute required.
* WEB - launch the URL, must also have url attribute.
type: string
enum:
- DISTI_COPY
- NONE
- SMARTSHEET_ITEM
- SOURCE_SHEET
- WEB
folderId:
description: If interactionType = SMARTSHEET_ITEM this is the folder to
open.
type: number
reportId:
description: If interactionType = SMARTSHEET_ITEM this is the report to
open.
type: number
sheetId:
description: If interactionType = SMARTSHEET_ITEM this is the sheet to open.
type: number
sightId:
description: If interactionType = SMARTSHEET_ITEM this is the dashboard
to open.
type: number
url:
description: If interactionType = WEB this is the URL to launch.
type: string
workspaceId:
description: If interactionType = SMARTSHEET_ITEM this is the workspace
to open.
type: number
Workspace:
description: Can contain dashboards, folders, reports, sheets, and templates.
type: object
properties:
accessLevel:
$ref: '#/components/schemas/Discussion/properties/accessLevel'
id:
description: Workspace Id.
type: number
favorite:
description: Returned only if the user has marked the workspace as a favorite
in their "Home" tab (value = true).
type: boolean
folders:
description: Folders contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/folders/items'
name:
description: Workspace name.
type: string
permalink:
description: URL that represents a direct link to the workspace in Smartsheet.
type: string
reports:
description: Reports contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/reports/items'
sheets:
description: Sheets contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/sheets/items'
sights:
description: Dashboards contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/sights/items'
templates:
description: Templates contained in workspace.
type: array
items:
$ref: '#/components/schemas/Folder/properties/templates/items'
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.smartsheet.com/b/authorize
tokenUrl: https://api.smartsheet.com/2.0/token
scopes:
ADMIN_SHEETS: Modify sheet structure, including column definition, publish
state, etc.
ADMIN_SIGHTS: Modify dashboards structure.
ADMIN_USERS: Add and remove users from your Smartsheet organization account;
create groups and manage membership.
ADMIN_WEBHOOKS: Create, delete, and update webhooks; get all webhooks;
reset shared secret.
ADMIN_WORKSPACES: Create and manage workspaces and folders, including
sharing.
CREATE_SHEETS: Create new sheets.
CREATE_SIGHTS: Create new dashboards.
DELETE_SHEETS: Delete sheets.
DELETE_SIGHTS: Delete dashboards.
READ_CONTACTS: Retrieve contacts.
READ_EVENTS: Retrieve events.
READ_SHEETS: Read all sheet data, including attachments, discussions,
and cell data.
READ_SIGHTS: Read all dashboards data.
READ_USERS: Retrieve users and groups for your Smartsheet organization
account.
SHARE_SHEETS: Share sheets, including sending sheets as attachments.
SHARE_SIGHTS: Share dashboards.
WRITE_SHEETS: Insert and modify sheet data, including attachments, discussions,
and cell data.
APIToken:
scheme: bearer
type: http
description: API Token
| |