FormatDetails

Smartsheet OpenAPI Reference (2.0.0)

Welcome to the OpenAPI reference documentation for the Smartsheet API!

IMPORTANT:
The Smartsheet API is restricted to users on Business and Enterprise plans
The Developer Agreement governs the use of the Smartsheet API and Smartsheet software development kits (SDKs)

QUICKLINKS

Base URL:
```
https://api.smartsheet.com/2.0/
```
Getting started: Generate an API access token and make a request.
Changelog: See the latest API updates.
Schemas: View the object schemas not explicitly listed in the resource sections.
Error codes: Look up common API error codes.
Guides: Learn various ways of using the API with the help of our Guides.

Browse the Smartsheet API operations by resource on the left and start building with the Smartsheet API!

Download OpenAPI description

openapi.json

openapi.yaml

Servers

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

https://api.smartsheet.eu/2.0/

https://api.smartsheet.au/2.0/

Alternate Email addresses

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.

Operations

Attachments

Attachments can exist on a comment (that is, within a discussion), on a row, or on a sheet.

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 allows you to add a single file attachment to the specified object.

For example, you can perform a simple upload to attach a file to a sheet, attach a file to a row, or attach a file to a comment.

A multipart upload allows you to add a single file attachment to the specified object (that is, attach a file to a sheet, row, or comment), or to create an object and attach a file using a single request.

For example, you can perform a multipart upload to add a new comment that contains a single file attachment or to add a new discussion to a sheet that contains a single file attachment.

The max file size for uploads through the API is limited to 30mb.

NOTE: This is a resource-intensive operation. If you encounter an error, see Rate Limiting.

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 JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

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 JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

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.

Operations

Automation Rules

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.

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.

Operations

Cell Images

A cell image is an image that has been uploaded to a cell within a sheet.

Operations

Cells

A collection of cells comprises each row in a sheet.

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

Column Type	Possible Types for Cell.value	Returns Cell.displayValue?
ABSTRACT_DATETIME	string: a project date and time in ISO-8601 format, or a free-form text value. number: see Dates and Times for how to request dates to be returned as numbers.	No.
CHECKBOX	Boolean: true if the checkbox is checked, false if unchecked, no value if the cell hasn't been touched yet. string: a free-form text value.	No.
CONTACT_LIST	string: an email address representing a contact, or a free-form text value.	Yes: same as value for free-form strings; for contacts, the contact's name if any, else their email address.
DATE	string: a date in ISO-8601 format, or a free-form text value. number: see Dates and Times for how to request dates to be returned as numbers.	No.
DURATION	string: a duration value such as "4d 6h 30m" in the user's locale, or a free-form text value. See the Help Center 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 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 containing Predecessor objects.
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.

If, however, you want the same flexibility as the Smartsheet Web app, you can disable the strict rules, and we'll do our best to make sense of it. To enable lenient parsing simply include "strict": false in the Cell object in your request body.

NOTE: How does strict cell value parsing compare to cell validation settings? Strict cell value parsing determines how string values are parsed. It is set on a per-call basis. In contrast, cell validation is part of the column definition. The overrideValidation property is restricted to sheet admins and does not override strict parsing.

The parsing rules for the various column types are as follows:

ABSTRACT_DATETIME

Value	Description
lenient	Smartsheet attempts to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, Smartsheet recognizes the date and stores it as such. All other values are simply text values.
strict	The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of numericDates set to true to have Smartsheet convert epoch time to human readable dates. See Dates and Times for more information.

CHECKBOX

Value	Description
lenient	Boolean values and string values of true and false are handled the same as strict. All other values are saved as text values.
strict	Only Boolean values (true or false) are valid.

CONTACT_LIST

Value	Description
lenient	If the value is a valid email address, Smartsheet handles it the same as strict. If not, Smartsheet saves the value as a text value.
strict	The value must be a valid email address. If displayValue is set, Smartsheet uses that as the name; otherwise, if Smartsheet finds a match among the the access token owner's contacts, Smartsheet associates this cell with that existing contact.

NOTE: See the Contact List Columns section for more information.

DATE

Value	Description
lenient	Smartsheet attempts to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, Smartsheet recognizes the date and stores it as such. All other values are simply text values.
strict	The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of numericDates set to true to have Smartsheet convert epoch time to human readable dates. See Dates and Times for more information.

DURATION

Value	Description
lenient	Numeric values are treated as duration values in days. String values which are valid duration strings in the user's locale are treated as durations, and any other values are treated as free-form text values.
strict	Only valid duration strings in the user's locale are valid. Information on duration strings can be found in the Help Center.

NOTE: You may use the query string parameter projectParseLocale with a supported locale string to force parsing in the specified locale (for example, using en_US lets you send in English values regardless of the user's locale).

MULTI_CONTACT_LIST

Value	Description
N/A	Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

MULTI_PICKLIST

Value	Description
N/A	Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

PICKLIST

Value	Description
lenient	All numeric and text values are valid. Formatted numbers are parsed like TEXT_NUMBER formatted numbers.
strict	The value must be a string and must be one of the options for the picklist.

PREDECESSOR

Value	Description
N/A	Set using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

TEXT_NUMBER

Value	Description
lenient	All numeric and text values are valid. Formatted numbers passed as text values, such as currencies ("$5,000"), percentages ("50%"), or decimals ("100.5") are parsed to their numeric equivalents, based on the locale of the access token owner, with the proper formatting enabled for the cell.
strict	All numeric and text values are valid and are interpreted literally.

NOTE: The Smartsheet application only supports numeric values in the range -9007199254740992 to 9007199254740992. If using strict parsing, any numeric value outside that range results in error code 1148. If using lenient parsing, the value is silently converted to text.

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

Operations

Columns

A column is a component of a sheet or report.

Column Types

Smartsheet supports the following standard column types, which are represented in a Column object with a type attribute set to one of the following:

Column Type	Column.type Value	Notes
Checkbox	CHECKBOX	Checkbox, star, and flag types
Contact List	CONTACT_LIST	List containing contacts or roles for a project. NOTE: You can use the contactOptions property to specify a pre-defined list of values for the column, which can also become lanes in card view.
Contact List	MULTI_CONTACT_LIST	List where single cells can contain more than one contact. Only visible when using a query parameter of level and the value appropriate to the dashboard, report, or sheet that you are querying. To see email addresses behind the display names, combine an include=objectValue query parameter with a level query parameter.
Date	DATE
Date/Time	ABSTRACT_DATETIME	Represents a project sheet's start and end dates. Only for dependency-enabled project sheets The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) Additionally, the API does not support updating data in the "End Date" column under any circumstance, and does not support updating data in the "Start Date" column if "Predecessor" is set for that row.
Date/Time	DATETIME	Used only by the following system-generated columns: 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. Only for dependency-enabled project sheets
Text/Number	TEXT_NUMBER

NOTE: See the Cell Reference section for information on getting and setting cell values for the different column types.

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:

A flag symbol

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, with the Column.systemColumnType attribute set to one of the following:

Column.systemColumnType Value	Column Type	Notes
AUTO_NUMBER	TEXT_NUMBER	Columns of this system column type include an AutoNumberFormat object that describes the mask used to generate the value.
CREATED_BY	CONTACT_LIST
CREATED_DATE	DATETIME
MODIFIED_BY	CONTACT_LIST
MODIFIED_DATE	DATETIME

Operations

Comments

A discussion is a container for a number of individual comments in a threaded conversation. For more details, see the Discussion section.

This section describes operations on an individual comment within a discussion thread.

To retrieve all discussions and comments for an entire sheet, use List Discussions with the query parameter include=comments.
To retrieve all discussions and comments associated with a row, use List Row Discussions with the query parameter include=comments.

A comment can contain one or more attachments.

Comment Attachments

For details about working with a comment's attachments, see Attachments.

Operations

Contacts

A contact is a user's personal contact in Smartsheet (as described in the Help Center article, Managing Contacts.

Operations

Cross-sheet References

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.

Operations

Dashboards

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.

Operations

Discussions

A discussion is a container for a collection of individual comments within a single thread. A discussion can exist on a row or a sheet.

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. A discussion is a collection of one or more comments, each of which may contain attachments.

Discussion Attachments

For details about working with the attachments within a discussion, see Attachments.

Discussion Comments

For details about working with a discussion's comments, see Comments.

Operations

Events

Smartsheet uses event objects to capture actions such as creating, updating, loading, deleting, and more for items such as sheets, reports, dashboards, attachments, and users. With Event Reporting, you can use the operations described here to programmatically retrieve these events.

NOTE: Event Reporting is a premium add-on available for Enterprise and Advanced Work Management plans only. For details on the add-on, please contact our Sales Team.

Event types

All events derive from the Event schema. Each event type overrides Event's objectType and action properties with its specific object type and a typical action performed on that object. Furthermore, each event type's additionalDetails object has properties specific to the event type.

See Event types for the complete event listing, details, and example objects.

System users

System components perform some actions in Smartsheet. Therefore, the userId property in some response payloads refers to a system user--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 system users are listed 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

Operations

Favorites

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

Operations

Folders

A folder can exist in a user's Sheets folder Home, in a folder, or in a workspace.

Operations

Group Members

A group member is a user that belongs to a group.

Operations

Groups

A group is a collection of group members.

Operations

Home

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.

NOTE: The GET /home endpoint is deprecated. Use GET /folders/personal to get shared items and GET /workspaces/ to get workspaces.

Home Folders

For details about working with folders in the user's Sheets folder (that is, at the Home level), see Folders.

Home Sheets

For details about working with sheets in the user's Sheets folder (that is, at the Home level), see Sheets.

Operations

Imports

Import CSV or XLSX data into a new sheet.

Operations

Proofs

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.

Operations

Reports

A report is a filtered view of the data from one or more sheets. Like a sheet, a report is comprised of columns, rows, and cells, and may optionally contain attachments and discussions. 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.

Report Cells

For details about working with a report's cells, see Cells.

Report Columns

For details about working with a report's columns, see Columns.

Report Discussions

For details about working with a report's discussions, see Discussions.

Report Rows

For details about working with a report's rows, see Rows.

Operations

Rows

A row is a component of a sheet or report. Each row is composed of a collection of cells, and may optionally contain discussions or attachments.

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.

Row Cells

For details about working with a row's cells, see Cells.

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

Row Discussions

For details about working with a row's discussions, see Discussions.

Row Include Flags

Endpoints which return rows (for example, Get Sheet, Get Row) support the optional include query string parameter. If specified, the value of the include parameter is a comma-delimited list of flags that indicate additional attributes to be included in each Row object within the response.

Include Flag	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 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 Cell formatting.
objectValue	Includes objectValue attribute on cells containing values. For more information see Cell Reference.
rowPermalink	Includes permalink attribute that represents a direct link to the row 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, the default behavior is for Smartsheet to put the new row at the bottom of the sheet. And when you update a row, 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 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}`

Operations

Search

Search a specific sheet or search across all sheets that a user can access. If you have not used the public API in a while, we will need to provision your data. This could take up to 24 hours so please check back later!

Operations

Send via Email

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.

Send Rows

For details about sending rows via email, see Send Rows via Email.

Send Sheet

For details about sending a sheet via email, see Send Sheet via Email.

Send Update Request

For details about sending an update request via email, see Create an Update Request.

Server Info

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

Operations

Sheet Summary

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.

Operations

Sheets

A sheet can exist in a user's Sheets folder (Home), in a folder, or in a workspace. It is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

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.

Sheet Cells

For details about working with a sheet's cells, see Cells.

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

Sheet Columns

For details about working with a sheet's columns, see Columns.

Sheet Discussions

There are two ways to get discussion-related information for a sheet:

Operation	Returns
Get Sheet (with include parameter value discussions)	Response does not contain the comments
that comprise each discussion.
List Discussions (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.

Sheet Rows

For details about working with a sheet's rows, see Rows.

Operations

Templates

A template can be used to create a sheet, as described for the Create sheet in folder endpoint and the Create sheet in workspace endpoint.

Operations

Tokens

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.

Operations

Update Requests

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.

Operations

Users

The users API supports user CRUD operations, seat type operations, and activation/deactivation operations.

Note: Users are typically defined by the organization account, and then role within the organization, for example admin.

Users guides

To learn more about user-related resources and how to manage them, see the Users guide articles, including the Automate user seat type management guide.

Operations

Webhooks

Smartsheet webhooks are powerful tools for building custom integrations and automating processes. Instead of constantly polling for changes, with webhooks you can configure your applications to receive real-time notifications when specific Smartsheet events occur.

Webhooks guides

To learn more about webhooks and how to use them, see the Webhooks guide articles, including these:

For plan-level webhooks, check out our Automate user seat type management guide.

Continue on to dive into webhook object schemas and operations.

Operations

Workspaces

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.

Workspace Folders

For details about working with folders in a workspace, see Folders.

Workspace Sheets

For details about working with sheets in a workspace, see Sheets.

Operations

Schemas

FontFamily

namestring

Name of the font family.

Example: "Arial"

traitsArray of strings

Platform-independent traits of the font family. Contains one of the listed enum values.

Items Enum"sans-serif""serif"

Example: ["sans-serif"]

{
  "name": "Arial",
  "traits": [
    "sans-serif"
  ]
}

FormatDetails

paperSizestring

Specifies paper size.

Enum"A0""A1""A2""A3""A4""ARCHID""LEGAL""LETTER""WIDE"

Example: "LETTER"

{
  "paperSize": "LETTER"
}

FormatTables

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.

defaultsstring

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.

Example: ",,1,1,,,,,,,,,,,,,"

boldArray of strings

Example: ["none","on"]

colorArray of strings

The default setting is "none". Typically this is black text and a white background.

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

currencyArray of objects(Currency)

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

dateFormatArray of strings

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

decimalCountArray of strings

Example: ["0","1","2","3","4","5"]

fontFamilyArray of objects(FontFamily)

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

fontSizeArray of strings

Example: ["8","9","10","12","14","16","18","20","24","28","32","36"]

horizontalAlignArray of strings

The default setting is "default" which is equivalent to "left".

Example: ["default","left","center","right"]

italicArray of strings

Example: ["none","on"]

numberFormatArray of strings

Example: ["none","NUMBER","CURRENCY","PERCENT"]

strikethroughArray of strings

Example: ["none","on"]

textWrapArray of strings

Example: ["none","on"]

thousandsSeparatorArray of strings

Example: ["none","on"]

underlineArray of strings

Example: ["none","on"]

verticalAlignArray of strings

The default setting is "default" which is equivalent to "top".

Example: ["default","top","middle","bottom"]

{
  "defaults": ",,1,1,,,,,,,,,,,,,",
  "bold": [
    "none",
    "on"
  ],
  "color": [
    "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": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "dateFormat": [
    "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": [
    "0",
    "1",
    "2",
    "3",
    "4",
    "5"
  ],
  "fontFamily": [
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "fontSize": [
    "8",
    "9",
    "10",
    "12",
    "14",
    "16",
    "18",
    "20",
    "24",
    "28",
    "32",
    "36"
  ],
  "horizontalAlign": [
    "default",
    "left",
    "center",
    "right"
  ],
  "italic": [
    "none",
    "on"
  ],
  "numberFormat": [
    "none",
    "NUMBER",
    "CURRENCY",
    "PERCENT"
  ],
  "strikethrough": [
    "none",
    "on"
  ],
  "textWrap": [
    "none",
    "on"
  ],
  "thousandsSeparator": [
    "none",
    "on"
  ],
  "underline": [
    "none",
    "on"
  ],
  "verticalAlign": [
    "default",
    "top",
    "middle",
    "bottom"
  ]
}

Smartsheet OpenAPI Reference (2.0.0)

Alternate Email addresses

Attachments

Post an Attachment

Multipart Uploads

Simple Uploads

Automation Rules

Disabled Reasons for Automation Rules

Cell Images

Cells

Cell Links

Cell Reference

Cell Value Representation

Cell Value Parsing

Contact List Columns

Hyperlinks

Images in Cells

Columns

Column Types

Symbol Columns

System Columns

Comments

Comment Attachments

Contacts

Cross-sheet References

Dashboards

Discussions

Discussion Attachments

Discussion Comments

Events

Event types

System users

Favorites

Folders

Group Members

Groups

Home

Home Folders

Home Sheets

Imports

Proofs

Reports

Report Attachments

Report Cells

Report Columns

Report Discussions

Report Rows

Rows

Row Attachments

Row Cells

Row Discussions

Row Include Flags

Specify Row Location

Search

Send via Email

Send Report

Send Rows

Send Sheet

Send Update Request

Server Info

Sharing

Sheet Summary

Sheets

Sheet Attachments

Sheet Cells

Sheet Columns

Sheet Discussions

Sheet Rows

Templates

Tokens

Update Requests

Users

Users guides

Webhooks

Webhooks guides

Workspaces

Workspace Folders

Workspace Sheets

Schemas

FontFamily