Smartsheet logo

Methods

List Dashboards

Gets a list of all dashboards that the user has access to.

Authorizations:
APITokenOAuth2 (READ_SIGHTS)
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.

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/sights \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

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

Get Dashboard

Gets the specified dashboard.

Authorizations:
APITokenOAuth2 (READ_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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:

  • objectValue - when used in combination with a level query parameter, includes the email addresses for multi-contact data.
  • source - the Source object for any Sight that was created from another Sight, if any
Enum: "objectValue" "source"
level
integer
Default: 0

Specifies whether new functionality, such as multi-contact data is returned in a backwards-compatible, text format (level=0, default), multi-contact data (level=2), multi-picklist data (level=3), or Metric widget with sheet summary (level=4).

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.

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/sights/{sightId}?level=4 \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "backgroundColor": "string",
  • "defaultWidgetBackgroundColor": "string",
  • "columnCount": 0,
  • "favorite": true,
  • "source": {
    },
  • "widgets": [
    ],
  • "workspace": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "id": 0,
  • "accessLevel": "ADMIN",
  • "permalink": "string",
  • "name": "string"
}

Update Dashboard

Updates (renames) the specified dashboard.

Authorizations:
APITokenOAuth2 (ADMIN_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight being accessed.

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

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

Dashboard name.

Responses

Request samples

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

Response samples

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

Delete Dashboard

Deletes the dashboard specified in the URL.

Authorizations:
APITokenOAuth2 (DELETE_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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/sights/{sightId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

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

Copy Dashboard

Creates a copy of the specified dashboard.

Authorizations:
APITokenOAuth2 (CREATE_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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
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
{
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Move Dashboard

Moves the specified dashboard to a new location.

Authorizations:
APITokenOAuth2 (CREATE_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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
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
{
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Set Dashboard Publish Status

Publishes or unpublishes a dashboard.

Authorizations:
APITokenOAuth2 (ADMIN_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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
readOnlyFullAccessibleBy
string

Indicates who can access the 'Read-Only Full' view of the published dashboard. Only returned in the response if readOnlyFullEnabled = true.

  • ALL - available to anyone who has the link.
  • ORG - available only to members of the dashboard owner's Smartsheet organization account.
  • SHARED - available only to users shared to the item.

If readOnlyFullEnabled is set to true in the request, but readOnlyFullAccessibleBy is not specified, the value of readOnlyFullAccessibleBy defaults to the organization-level 'Dashboard Publishing' setting (if the dashboard owner belongs to an organization account) or to ALL (if the dashboard owner does not belong to an organization account).

Enum: "ALL" "ORG"
readOnlyFullEnabled
required
boolean

If true, a rich version of the dashboard is published with the ability to use shortcuts and widget interactions.

Responses

Request samples

Content type
application/json
{
  • "readOnlyFullAccessibleBy": "ALL",
  • "readOnlyFullEnabled": true
}

Response samples

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

Share Dashboard

Shares a dashboard with the specified users and groups.

Authorizations:
APITokenOAuth2 (SHARE_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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
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
{
  • "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"
}

Response samples

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

List Dashboard Shares

Gets a list of all users and groups to whom the specified dashboard is shared, and their access level.

Authorizations:
APITokenOAuth2 (READ_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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/sights/{sightId}/shares \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

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

Get Dashboard Share

Gets a list of all users and groups to whom the specified dashboard is shared, and their access level.

Authorizations:
APITokenOAuth2 (READ_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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/sights/{sightId}/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 Dashboard Share

Deletes the share specified in the URL.

Authorizations:
APITokenOAuth2 (SHARE_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight being accessed.

shareId
required
string

Share Id.

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/sights/{sightId}/shares/{shareId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

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

Update Dashboard Share

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

Authorizations:
APITokenOAuth2 (SHARE_SIGHTS)
path Parameters
sightId
required
string

SightID of the sight 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": { }
}
➔ Next to Discussions Basics