Methods

Get Favorites

Gets a list of all of the user's favorite items.

Authorizations:

APITokenOAuth2 (READ_SHEETS)

query Parameters

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.
include	string A comma-separated list of optional elements to include in the response. Enum: "directId" "name"

header Parameters

Authorization	string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
x-smar-sc-actor-id	string UserId of the user Example: 100012

Responses

Request samples

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

Response samples

200
default

Content type

application/json

{"pageNumber": 1,
"pageSize": 50,
"totalPages": 25,
"totalCount": 136,
"data": [{"objectId": 0,
"type": "folder"
}
]
}

Add Favorites

Adds one or more favorite items for the current user. This operation supports both single-object and bulk semantics. For more information, see Optional Bulk Operations. If called with a single Favorite object, and that favorite already exists, error code 1129 is returned. If called with an array of Favorite objects, any objects specified in the array that are already marked as favorites are ignored and omitted from the response.

Authorizations:

APITokenOAuth2 (ADMIN_WORKSPACES)

header Parameters

Authorization	string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
x-smar-sc-actor-id	string UserId of the user Example: 100012
Content-Type	string Default: application/json Required for POST and PUT requests. Defines the structure for the request body.

Request Body schema: application/json

A list of favorites to be added.

One of

objectId	number The Id of the favorited item. If type is template, only private sheet-type template Id is allowed.
type	string Enum: "folder" "report" "sheet" "sight" "template" "workspace"

Responses

Request samples

Content type

application/json

[ ]

Response samples

200
default

Content type

application/json

{"message": "SUCCESS",
"resultCode": 0,
"result": {"objectId": 0,
"type": "folder"
}
}

Delete Multiple Favorites

Deletes all favorites with the same type for the user.

Authorizations:

APITokenOAuth2 (ADMIN_WORKSPACES)

path Parameters

favoriteType

required

string

The favorite type.

Enum: "folder" "report" "sheet" "sight" "template" "workspace"

query Parameters

objectIds

required

string

A comma-separated list of Ids of the favorited item.

header Parameters

Authorization	string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
x-smar-sc-actor-id	string UserId of the user Example: 100012

Responses

Request samples

curl 'https://api.smartsheet.com/2.0/favorites/{favoriteType}?objectIds=favoriteId1,favoriteId2' \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

200
default

Content type

application/json

{"message": "SUCCESS",
"resultCode": 0
}

Delete Favorite

Deletes a single favorite from the user's list of favorite items by type and ID.

Authorizations:

APITokenOAuth2 (ADMIN_WORKSPACES)

path Parameters

favoriteType required	string The favorite type. Enum: "folder" "report" "sheet" "sight" "template" "workspace"
favoriteId required	number Favorite Id, e.g., sheet Id, report Id.

header Parameters

Authorization	string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
x-smar-sc-actor-id	string UserId of the user Example: 100012

Responses

Request samples

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

Response samples

200
default

Content type

application/json

{"message": "SUCCESS",
"resultCode": 0
}

Is Favorite

Checks whether an item has been tagged as a favorite for the current user by type and ID.

Authorizations:

APITokenOAuth2 (READ_SHEETS)

path Parameters

favoriteType required	string The favorite type. Enum: "folder" "report" "sheet" "sight" "template" "workspace"
favoriteId required	number Favorite Id, e.g., sheet Id, report Id.

query Parameters

include

string

A comma-separated list of optional elements to include in the response.

Enum: "directId" "name"

header Parameters

Authorization	string API Access Token used to authenticate requests to Smartsheet APIs. Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
x-smar-sc-actor-id	string UserId of the user Example: 100012

Responses

Request samples

cURL
C#
Python

curl -i -X GET \
  'https://api.smartsheet.com/2.0/favorites/{favoriteType}/{favoriteId}?include={directId}' \
  -H 'Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789' \
  -H 'x-smar-sc-actor-id: 100012'

Response samples

200
default

Content type

application/json

{"objectId": 0,
"type": "folder"
}