Smartsheet logo

Methods

Create Sheet in Folder

Creates a sheet from scratch or from the specified template in the specified folder.

Authorizations:
APITokenOAuth2 (CREATE_SHEETS)
path Parameters
folderId
required
number

Folder Id where you can create sheets, sights, reports, templates, and other folders.

query Parameters
include
string

Additional parameter to create a sheet from template. A comma-separated list of elements to copy from the template.

Enum: "attachments" "cellLinks" "data" "discussions" "filters" "forms" "ruleRecipients" "rules"
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

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

Request Body schema: application/json

Sheet to create.

One of
Array of objects
name
string

Sheet name.

Responses

Request samples

Content type
application/json
{
  • "fromId": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

List Sheets

Gets a list of all sheets that the user has access to. The list contains an abbreviated Sheet object for each sheet.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

include
string

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
Enum: "sheetVersion" "source"
includeAll
boolean
Default: false

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

string or number

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.

numericDates
boolean
Default: false

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.

page
number
Default: 1

Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, you'll receive an empty data set.

pageSize
number
Default: 100

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.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/sheets \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "pageNumber": 1,
  • "pageSize": 50,
  • "totalPages": 25,
  • "totalCount": 136,
  • "data": [
    ]
}

Create Sheet in "Sheets" Folder

Creates a sheet from scratch or from the specified template in the user's Sheets folder (Home). For subfolders, use Create Sheet in Folder.

Authorizations:
APITokenOAuth2 (CREATE_SHEETS)
query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

include
string

Additional parameter to create a sheet from template. A comma-separated list of elements to copy from the template.

Enum: "attachments" "cellLinks" "data" "discussions" "filters" "forms" "ruleRecipients" "rules"
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

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

Request Body schema: application/json

Sheet to create.

One of
Array of objects
name
string

Sheet name.

Responses

Request samples

Content type
application/json
{
  • "fromId": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Get Sheet

Gets a sheet in the format specified, based on the sheet Id.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

include
string

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 owner's email address and the owner's 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.
Enum: "attachments" "columnType" "crossSheetReferences" "discussions" "filters" "filterDefinitions" "format" "ganttConfig" "objectValue" "ownerInfo" "rowPermalink" "source" "writerInfo"
exclude
string

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
Enum: "filteredOutRows" "linkInFromCellDetails" "linksOutToCellsDetails" "nonexistentCells"
columnIds
string

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.

filterId
string

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.

ifVersionAfter
integer

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.

level
integer
Default: 1

Specifies whether new functionality, such as multi-contact data is returned in a backwards-compatible, text format (level=0, default), multi-contact data (level=1), or multi-picklist data (level=2).

pageSize
number
Default: 100

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.

page
number
Default: 1

Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, you'll receive an empty data set.

paperSize
string
Default: "LETTER"

applies to PDF format only

Enum: "LETTER" "LEGAL" "WIDE" "ARCHD" "A4" "A3" "A2" "A1" "A0"
rowIds
string

A comma-separated list of row Ids on which to filter the rows included in the result.

rowNumbers
string

A comma-separated list of row numbers on which to filter the rows included in the result. Non-existent row numbers are ignored.

string or number

Filter to return only rows that have been modified since the date/time provided. Date should be in ISO-8601 format.

Example: rowsModifiedSince=2020-01-30T13:25:32-07:00
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Accept
string

The Accept request-header field can be used to specify certain media types which are acceptable for the response.

Responses

Request samples 

// Sample 1: Get sheet
curl https://api.smartsheet.com/2.0/sheets/{sheetId}?level=2&include=objectValue \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"
 
// Sample 2: Get sheet as Excel
curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Accept: application/vnd.ms-excel" \
-o output.xlsx

// Sample 3: Get sheet as PDF
curl 'https://api.smartsheet.com/2.0/sheets/{sheetId}?paperSize=A1' \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Accept: application/pdf"
-o  output.pdf

// Sample 4: Get sheet as CSV
curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Accept: text/csv" \
-o output.csv

Response samples

Content type
application/json
application/json
application/pdf
application/vnd.ms-excel
text/csv
{
  • "version": 0
}

Delete Sheet

Deletes the sheet specified in the URL.

Authorizations:
APITokenOAuth2 (DELETE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/sheets/{sheetId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0
}

Update Sheet

Updates the sheet specified in the URL. To modify sheet contents, see Add Rows, Update Rows, Add Columns, and Update Column. 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).

Authorizations:
APITokenOAuth2 (ADMIN_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json

Sheet object limited to the following attributes:

  • name (optional).
  • projectSettings (optional): ProjectSettings object, containing at least one of the projectSettings attributes, for updating this sheet's project settings and dependencies.
  • userSettings (optional): 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.
name
string

Sheet name.

object

Represents the project settings dependencies for a specific sheet. Project settings may be updated on sheets that the user has editor access.

object

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

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "projectSettings": {
    },
  • "userSettings": {
    }
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Copy Sheet

Creates a copy of the specified sheet.

Authorizations:
APITokenOAuth2 (CREATE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
include
string

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.
Enum: "attachments" "cellLinks" "data" "discussions" "filters" "forms" "ruleRecipients" "rules" "shares"
exclude
string

When specified with a value of sheetHyperlinks, excludes this category from the response

Value: "sheetHyperlinks"
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

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

Request Body schema: application/json

Destination where to create a copy of the specified sheet.

destinationId
number

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.

destinationType
string Nullable

Type of the destination container.

Enum: "folder" "home" "workspace"
newName
string

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.

Responses

Request samples

Content type
application/json
{
  • "destinationId": 0,
  • "destinationType": "folder",
  • "newName": "string"
}

Response samples

Content type
application/json
{
  • "version": 0,
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Send Sheet via Email

Sends the sheet as a PDF attachment via email to the designated recipients.

Authorizations:
APITokenOAuth2 (SHARE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

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

Request Body schema: application/json

SheetEmail object

format
string

One of the following values: EXCEL, PDF, or PDF_GANTT.

object
ccMe
boolean

Indicates whether to send a copy of the email to the sender.

message
string

The message of the email.

Array of objects or objects

Array of recipients.

subject
string

The subject of the email.

Responses

Request samples

Content type
application/json
{
  • "format": "string",
  • "formatDetails": {
    },
  • "ccMe": true,
  • "message": "string",
  • "sendTo": [
    ],
  • "subject": "string"
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0
}

Move Sheet

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.

Authorizations:
APITokenOAuth2 (CREATE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

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

Request Body schema: application/json

Destination to move the specified sheet.

destinationId
number

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.

destinationType
string Nullable

Type of the destination container.

Enum: "folder" "home" "workspace"

Responses

Request samples

Content type
application/json
{
  • "destinationId": 0,
  • "destinationType": "folder"
}

Response samples

Content type
application/json
{
  • "version": 0,
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Get Sheet Publish Status

Gets the sheet's 'Publish' settings.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/publish \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "icalEnabled": true,
  • "icalUrl": null,
  • "readOnlyFullAccessibleBy": "ALL",
  • "readOnlyFullDefaultView": "CALENDAR",
  • "readOnlyFullEnabled": true,
  • "readOnlyFullShowToolbar": true,
  • "readOnlyFullUrl": "string",
  • "readOnlyLiteEnabled": true,
  • "readOnlyLiteSslUrl": "string",
  • "readOnlyLiteUrl": "string",
  • "readWriteAccessibleBy": "ALL",
  • "readWriteDefaultView": "CALENDAR",
  • "readWriteEnabled": true,
  • "readWriteShowToolbar": true,
  • "readWriteUrl": "string"
}

Set Sheet Publish Status

Sets the publish status of the sheet and returns the new status, including the URLs of any enabled publishings.

Authorizations:
APITokenOAuth2 (ADMIN_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

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

Request Body schema: application/json

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

icalEnabled
boolean

If true, a webcal is available for the calendar in the sheet.

readOnlyFullAccessibleBy
string

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.

Enum: "ALL" "ORG" "SHARED"
readOnlyFullDefaultView
string

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.

Enum: "CALENDAR" "CARD" "GRID"
readOnlyFullEnabled
boolean

If true, a rich version of the sheet is published with the ability to download row attachments and discussions.

readOnlyFullShowToolbar
boolean
Deprecated

Indicates whether the left nav toolbar is displayed. The default, or true, is to display the toolbar. If false, hides the toolbar.

readOnlyLiteEnabled
boolean

If true, a lightweight version of the sheet is published without row attachments and discussions.

readWriteAccessibleBy
string

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.

Enum: "ALL" "ORG" "SHARED"
readWriteDefaultView
string

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.

Enum: "CALENDAR" "CARD" "GRID"
readWriteEnabled
boolean

If true,a rich version of the sheet is published with the ability to edit cells and manage attachments and discussions.

readWriteShowToolbar
boolean
Deprecated

Indicates whether the left nav toolbar is displayed. The default, or true, is to display the toolbar. If false, hides the toolbar.

Responses

Request samples

Content type
application/json
{
  • "icalEnabled": true,
  • "readOnlyFullAccessibleBy": "ALL",
  • "readOnlyFullDefaultView": "CALENDAR",
  • "readOnlyFullEnabled": true,
  • "readOnlyFullShowToolbar": true,
  • "readOnlyLiteEnabled": true,
  • "readWriteAccessibleBy": "ALL",
  • "readWriteDefaultView": "CALENDAR",
  • "readWriteEnabled": true,
  • "readWriteShowToolbar": true
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Share Sheet

Shares a sheet with the specified users and groups.

Authorizations:
APITokenOAuth2 (SHARE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

sendEmail
boolean
Default: false

Either true or false to indicate whether to notify the user by email. Default is false. If true, limit is 1000 emails.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json
One of
id
string

Share Id.

NOTE: unlike other Smartsheet object Ids, this Id is an alphanumeric string.

groupId
number

Group Id if the share is a group share, else null.

userId
number

User Id if the share is a user share, else null.

type
string

The type of this share. One of the following values: GROUP or USER.

accessLevel
string
Enum: "ADMIN" "COMMENTER" "EDITOR" "EDITOR_SHARE" "OWNER" "VIEWER"
ccMe
boolean

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.

email
string

User's primary email address for user shares; null for group shares.

message
string

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.

name
string

If a user share and user is also a contact, the user's full name. If a group share, the group's name.

scope
string

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).
subject
string

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.

Responses

Request samples

Content type
application/json
[ ]

Response samples

Content type
application/json
{
  • "version": 0,
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

List Sheet Shares

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.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

sharingInclude
string

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

Enum: "ITEM" "WORKSPACE"
includeAll
boolean
Default: false

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

page
number
Default: 1

Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, you'll receive an empty data set.

pageSize
number
Default: 100

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.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "pageNumber": 1,
  • "pageSize": 50,
  • "totalPages": 25,
  • "totalCount": 136,
  • "result": [
    ]
}

Get Sheet Share.

Gets the share specified in the URL.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

shareId
required
string

Share Id.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares/{shareId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "id": "string",
  • "groupId": 0,
  • "userId": 0,
  • "type": "string",
  • "accessLevel": "ADMIN",
  • "ccMe": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "email": "string",
  • "message": "string",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "scope": "string",
  • "subject": "string"
}

Delete Sheet Share

Deletes the share specified in the URL.

Authorizations:
APITokenOAuth2 (SHARE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

shareId
required
string

Share Id.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/shares/{shareId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

Content type
application/json
{
  • "version": 0,
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0
}

Update Sheet Share.

Updates the access level of a user or group for the specified sheet.

Authorizations:
APITokenOAuth2 (SHARE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

shareId
required
string

Share Id.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json
accessLevel
string
Enum: "ADMIN" "COMMENTER" "EDITOR" "EDITOR_SHARE" "OWNER" "VIEWER"

Responses

Request samples

Content type
application/json
{
  • "accessLevel": "ADMIN"
}

Response samples

Content type
application/json
{
  • "version": 0,
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": { }
}

Get Sheet Version

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
Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/version \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "version": 0
}

List Org Sheets

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.

Authorizations:
APITokenOAuth2 (ADMIN_USERS)
query Parameters
string or number

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.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/users/sheets \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "pageNumber": 1,
  • "pageSize": 50,
  • "totalPages": -1,
  • "totalCount": -1,
  • "data": [
    ]
}

Create Sheet in Workspace

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.

Authorizations:
APITokenOAuth2 (CREATE_SHEETS)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

include
string

Additional parameter to create a sheet from template. A comma-separated list of elements to copy from the template.

Enum: "attachments" "cellLinks" "data" "discussions" "filters" "forms" "ruleRecipients" "rules"
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

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

Request Body schema: application/json

Sheet to create.

One of
Array of objects
name
string

Sheet name.

Responses

Request samples

Content type
application/json
{
  • "fromId": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}
➔ Next to Related Items