Skip to content
/
List proof request action...

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

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

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://help.smartsheet.com/contact
Languages
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.

SchemasOperations

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:

HeaderDescription
Content-LengthThe length of the request payload.
Content-TypeMust 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:

HeaderDescription
Content-DispositionContains 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-TypeThe 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:

HeaderDescription
Content-Dispositionattachment 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-LengthMust 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-TypeCan 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.

SchemasOperations

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

ReasonDescription
APPROVAL_COLUMN_MISSINGThis rule's approval status column has been deleted.
APPROVAL_COLUMN_WRONG_TYPEThe approval column must be a dropdown column.
AUTOMATION_NOT_ENABLED_FOR_ORGTo create or edit automated actions, you need to upgrade your organization account to a Business or Enterprise plan.
COLUMN_MISSINGA column referenced by this rule has been deleted.
COLUMN_TYPE_INCOMPATIBLEA column referenced by this rule has been changed to an incompatible column type.
NO_POTENTIAL_RECIPIENTSThis 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_COLUMNSAll selected columns for this rule have been deleted.
SchemasOperations

Cell Images

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

SchemasOperations

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 TypePossible Types for Cell.valueReturns Cell.displayValue?
ABSTRACT_DATETIMEstring: 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.
CHECKBOXBoolean: 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_LISTstring: 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.
DATEstring: 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.
DURATIONstring: 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_LISTstring: 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_PICKLISTstring: 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.
PICKLISTstring: 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.
PREDECESSORstring: 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_NUMBERstring: 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

ValueDescription
lenientSmartsheet 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.
strictThe 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

ValueDescription
lenientBoolean values and string values of true and false are handled the same as strict. All other values are saved as text values.
strictOnly Boolean values (true or false) are valid.

CONTACT_LIST

ValueDescription
lenientIf the value is a valid email address, Smartsheet handles it the same as strict. If not, Smartsheet saves the value as a text value.
strictThe 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

ValueDescription
lenientSmartsheet 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.
strictThe 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

ValueDescription
lenientNumeric 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.
strictOnly 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

ValueDescription
N/ASet using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

MULTI_PICKLIST

ValueDescription
N/ASet using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

PICKLIST

ValueDescription
lenientAll numeric and text values are valid. Formatted numbers are parsed like TEXT_NUMBER formatted numbers.
strictThe value must be a string and must be one of the options for the picklist.

PREDECESSOR

ValueDescription
N/ASet using the objectValue attribute for the Cell object, which is inherently strict. See Cell Reference.

TEXT_NUMBER

ValueDescription
lenientAll 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.
strictAll 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.

SchemasOperations

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 TypeColumn.type ValueNotes
CheckboxCHECKBOXCheckbox, star, and flag types
Contact ListCONTACT_LISTList 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 ListMULTI_CONTACT_LISTList 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.
DateDATE
Date/TimeABSTRACT_DATETIMERepresents 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/TimeDATETIMEUsed only by the following system-generated columns:
  • Created (Date) (Column.systemColumnType = CREATED_DATE)
  • Modified (Date) (Column.systemColumnType = MODIFIED_DATE)
Dropdown ListPICKLISTCustom, RYG, Harvey ball, priority types, etc.
Dropdown ListMULTI_PICKLISTList 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.
DurationDURATIONOnly 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.)
PredecessorPREDECESSORDefines what must happen first in a project flow. For more information, see the Predecessor object. Only for dependency-enabled project sheets
Text/NumberTEXT_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

ValueExample
FLAGA flag symbol
STARA star symbol

Symbols for PICKLIST columns:

ValueExample
ARROWS_3_WAYAn arrows_3_way symbol
ARROWS_4_WAYAn arrows_4_way symbol
ARROWS_5_WAYAn arrows_5_way symbol
DECISION_SHAPESA decision_shapes symbol
DECISION_SYMBOLSA decision_symbols symbol
DIRECTIONS_3_WAYA directions_3_way symbol
DIRECTIONS_4_WAYA directions_4_way symbol
EFFORTAn effort symbol
HARVEY_BALLSA harvey_balls symbol
HEARTSA hearts symbol
MONEYA money symbol
PAINA pain symbol
PRIORITYA priority symbol
PRIORITY_HMLA priority_hml symbol
PROGRESSA progress symbol
RYGAn RYG symbol
RYGBAn RYGB symbol
RYGGAn RYGG symbol
SIGNALA signal symbol
SKIA ski symbol
STAR_RATINGA star_rating symbol
VCRA VCR symbol
WEATHERA weather symbol

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 ValueColumn TypeNotes
AUTO_NUMBERTEXT_NUMBERColumns of this system column type include an AutoNumberFormat object that describes the mask used to generate the value.
CREATED_BYCONTACT_LIST
CREATED_DATEDATETIME
MODIFIED_BYCONTACT_LIST
MODIFIED_DATEDATETIME
SchemasOperations

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.

SchemasOperations

Contacts

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

SchemasOperations

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.

SchemasOperations

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.

SchemasOperations

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.

SchemasOperations

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 userDescription
1688855062570884Data accessed/modified by Skype action (only possible if Smartsheet account is connected to Skype)
2814754969413508Data accessed/modified by Trello import action (only possible if Smartsheet account is connected to Trello)
3377704922834820Data accessed/modified due to Smartsheet cell-link
3940654876256132Data accessed/modified by the Smartsheet Automation system
5066554783098756Access to object published to any user in the Smartsheet organization account
5629504736520068Access to Smartsheet object published to anyone
6192454689941380Data accessed/modified by the Smartsheet Notification system
7881304550205316Data accessed/modified by Smartsheet Form submission
SchemasOperations

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
SchemasOperations

Folders

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

SchemasOperations

Group Members

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

SchemasOperations

Groups

A group is a collection of group members.

SchemasOperations

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.

SchemasOperations

Create proof discussion

Request

Creates a discussion on a proof.

Security
APIToken or OAuth2
Path
sheetIdnumberrequired

Sheet Id of the sheet being accessed.

proofIdstringrequired

Proof Id of the original proof

Headers
Authorizationstring

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
smartsheet-integration-sourcestring

Uses the following metadata to distinguish between human-initiated API requests and third-party service-initiated calls by AI Connectors or ITSM:

  • Integration source type
  • Organization name
  • Integration source name

Format:

TYPE,OrgName,SourceName

Examples:

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater

Example: AI,SampleOrg,My-AI-Connector-v2
Content-Typestring

Required for POST and PUT requests. Defines the structure for the request body.

Default application/json
Body
commentobject(Comment text)

Comment text object.

// Sample 1: create proof discussion (without attachment)
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/discussions \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Content-Type: multipart/form-data \
-X POST \
--data-binary "@/home/Downloads/test_b (4).pdf"

// Sample 2: create proof discussion (with attachment)
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/discussions \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Content-Type: multipart/form-data \
-X POST \
-F 'discussion={ "comment": { "text": "This text is the body of the first comment" } };type=application/json' \
-F "file=@/home/Downloads/test_b (4).pdf;type=application/octet-stream"
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/discussions' \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Responses

SUCCESS

Bodyapplication/json
versionnumber or null

New version of the sheet. Applicable only for operations which update sheet data.

messagestring

Message that indicates the outcome of the request. (One of SUCCESS or PARTIAL_SUCCESS.)

Enum"PARTIAL_SUCCESS""SUCCESS"
Example: "SUCCESS"
resultCodenumber
  • '0' Success
  • '3' Partial Success of Bulk Operation
Enum03
resultobject(Discussion)
Example Response Schema
application/json
{
  "version": 0,
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "accessLevel": "ADMIN",
    "id": 0,
    "comments": [ … ],
    "commentAttachments": [ … ],
    "commentCount": 0,
    "createdBy": { … },
    "lastCommentedAt": "2019-08-24T14:15:22Z",
    "lastCommentedUser": { … },
    "parentId": 0,
    "parentType": "ROW",
    "readOnly": true,
    "title": "string"
  }
}

List proof request actions

Request

Gets a summarized list of all request actions associated with the specified proof.

Note: For pagination guidance, refer to Pagination.

Security
APIToken or OAuth2
Path
sheetIdnumberrequired

Sheet Id of the sheet being accessed.

proofIdstringrequired

Proof Id of the original proof

Query
pagenumber

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.

Default 1
pageSizenumber

The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If only page is specified, defaults to a page size of 100. For reports, the default is 100 rows. If you need larger sets of data from your report, returns a maximum of 10,000 rows per request.

Default 100
includeAllboolean

If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified).

Default false
Headers
Authorizationstring

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
smartsheet-integration-sourcestring

Uses the following metadata to distinguish between human-initiated API requests and third-party service-initiated calls by AI Connectors or ITSM:

  • Integration source type
  • Organization name
  • Integration source name

Format:

TYPE,OrgName,SourceName

Examples:

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater

Example: AI,SampleOrg,My-AI-Connector-v2
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/requestactions \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Responses

OK.

Note: For pagination guidance, refer to Pagination.

Bodyapplication/json
pageNumbernumberread-only

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.

Example: 1
pageSizenumber or nullread-only

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.

Example: 50
totalPagesnumberread-only

The total number of pages in the full result set.

Example: 25
totalCountnumberread-only

The total number of items in the full result set.

Example: 136
dataArray of objects(Proof request action)

list of proof request actions

Example Response Schema
application/json
{
  "pageNumber": 1,
  "pageSize": 50,
  "totalPages": 25,
  "totalCount": 136,
  "data": [
    { … }
  ]
}

Delete proof requests

Request

Deletes all proof requests in a proof.

Security
APIToken or OAuth2
Path
sheetIdnumberrequired

Sheet Id of the sheet being accessed.

proofIdstringrequired

Proof Id of the original proof

Headers
Authorizationstring

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
smartsheet-integration-sourcestring

Uses the following metadata to distinguish between human-initiated API requests and third-party service-initiated calls by AI Connectors or ITSM:

  • Integration source type
  • Organization name
  • Integration source name

Format:

TYPE,OrgName,SourceName

Examples:

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater

Example: AI,SampleOrg,My-AI-Connector-v2
curl https://api.smartsheet.com/2.0/sheets/{sheetId}/proofs/{proofId}/requests \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Responses

SUCCESS

Bodyapplication/json
messagestring

Message that indicates the outcome of the request. (One of SUCCESS or PARTIAL_SUCCESS.)

Enum"PARTIAL_SUCCESS""SUCCESS"
Example: "SUCCESS"
resultCodenumber
  • '0' Success
  • '3' Partial Success of Bulk Operation
Enum03
Example Response Schema
application/json
{
  "message": "SUCCESS",
  "resultCode": 0
}

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.

SchemasOperations

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 FlagDescription
attachmentsIncludes row attachments array.
To include discussion attachments, both attachments and discussions must be present in the include list.
columnTypeIncludes columnType attribute in the row's cells indicating the type of the column the cell resides in.
discussionsIncludes row discussions array.
To include discussion attachments, both attachments and discussions must be present in the include list.
filtersIncludes filteredOut attribute indicating if the row should be displayed or hidden according to the sheet's filters.
formatIncludes format attribute on the row, its cells, or summary fields. See Cell formatting.
objectValueIncludes objectValue attribute on cells containing values. For more information see Cell Reference.
rowPermalinkIncludes permalink attribute that represents a direct link to the row in the Smartsheet application.
rowWriterInfoDEPRECATED Includes createdBy and modifiedBy attributes on the row, indicating the row's creator, and last modifier.
writerInfoIncludes 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.
DestinationRow AttributesExamples
Top of a sheettoTop{"toTop": true}
Bottom of a sheettoBottom{"toBottom": true}
Top of an indented section a.k.a., first child rowparentId{"parentId": 8896508249565060}
Bottom of an indented section a.k.a., last child rowparentId +
toBottom		{"parentId": 8896508249565060, "toBottom": true}
Below a specific row, at the same indent levelsiblingId{"siblingId": 8896508249565060}
Above a specific row, at the same indent levelsiblingId +
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}
SchemasOperations

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.

Schemas

Server Info

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

SchemasOperations

Sharing

Use the Sharing operations to control sharing of dashboards, reports, sheets, and workspaces.

SchemasOperations

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.

SchemasOperations

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:

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

SchemasOperations

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.

SchemasOperations

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.

SchemasOperations

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.

SchemasOperations

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.

SchemasOperations

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 Smartsheet webhooks in general, start with these Webhooks guide articles:

Resource-specific guides

To dive into webhooks on a specific resource, check out these guides:

Continue on to dive into webhook object schemas and operations.

SchemasOperations

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.

SchemasOperations

Schemas

Schemas