Smartsheet logo

Methods

List Reports

List all Reports accessible to the user.

Authorizations:
OAuth2 (READ_SHEETS)
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/reports \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{}

Get Report

Gets a report based on the specified ID

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
reportId
required
number

reportID of the report 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
  • discussions
  • proofs
  • format
  • objectValue - when used in combination with a level query parameter, includes the email addresses for multi-contact data
  • scope - adds the report's scope to the response
  • source - adds the Source object indicating which report the report was created from, if any
  • sourceSheets
Enum: "attachments" "discussions" "proofs" "format" "objectValue" "scope" "source" "sourceSheets"
exclude
string

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

Enum: "linkInFromCellDetails" "linksOutToCellsDetails"
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.

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=1), or multi-picklist data (level=3).

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 report
curl https://api.smartsheet.com/2.0/reports/{reportId}?level=3&include=objectValue \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"
 
// Sample 2: Get report as Excel
curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Accept: application/vnd.ms-excel" \
-o output.xlsx

// Sample 3: Get report as CSV
curl https://api.smartsheet.com/2.0/reports/{reportId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Accept: text/csv" \
-o output.csv

Response samples

Content type
application/json
application/json
application/vnd.ms-excel
text/csv
{
  • "scope": {
    },
  • "sourceSheets": [
    ],
  • "isSummaryReport": true,
  • "id": 0,
  • "fromId": 0,
  • "ownerId": 0,
  • "accessLevel": "ADMIN",
  • "attachments": [
    ],
  • "cellImageUploadEnabled": true,
  • "columns": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "crossSheetReferences": [
    ],
  • "dependenciesEnabled": true,
  • "discussions": [
    ],
  • "effectiveAttachmentOptions": [
    ],
  • "favorite": true,
  • "ganttEnabled": true,
  • "hasSummaryFields": true,
  • "isMultiPicklistEnabled": true,
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "owner": "string",
  • "permalink": "string",
  • "projectSettings": {
    },
  • "readOnly": true,
  • "resourceManagementEnabled": true,
  • "resourceManagementType": "NONE",
  • "rows": [
    ],
  • "showParentRowsForFilters": true,
  • "source": {
    },
  • "summary": {
    },
  • "totalRowCount": 0,
  • "userPermissions": {
    },
  • "userSettings": {
    },
  • "version": 0,
  • "workspace": {
    }
}

Send report via email

Sends the report as a PDF attachment via email to the designated recipients

Authorizations:
APITokenOAuth2 (SHARE_SHEETS)
path Parameters
reportId
required
number

reportID of the report 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
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
{
  • "version": 0,
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0
}

Gets a Report's publish settings

Get a Report's publish settings based on the specified ID

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
reportId
required
number

reportID of the report 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/reports/{reportId}/publish \ 
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "readOnlyFullAccessibleBy": "string",
  • "readOnlyFullDefaultView": "string",
  • "readOnlyFullEnabled": true,
  • "readOnlyFullShowToolbar": true,
  • "readOnlyFullUrl": "string"
}

Set a Report's publish status

Sets the publish status of the report and returns the new status, including the URL of any enabled publishing.

Authorizations:
APITokenOAuth2 (ADMIN_SHEETS)
path Parameters
reportId
required
number

reportID of the report 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 report:

  • If ALL, it is available to anyone who has the link.
  • If ORG, it is available only to members of the report owner's Smartsheet organization account.
  • If SHARED, it is available only to users shared to the item.

Only returned in a response if readOnlyFullEnabled = true.

readOnlyFullDefaultView
string

Indicates which view the user has set for a read-only, default view of the published report. Must be one of the following values: CALENDAR, CARD, or GRID.

readOnlyFullEnabled
boolean

(Required) If true, a rich version of the report 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.

readOnlyFullUrl
string

URL for 'Read-Only Full' view of the published report.

Only returned in a response if readOnlyFullEnabled = true.

Responses

Request samples

Content type
application/json
{
  • "readOnlyFullAccessibleBy": "string",
  • "readOnlyFullDefaultView": "string",
  • "readOnlyFullEnabled": true,
  • "readOnlyFullShowToolbar": true,
  • "readOnlyFullUrl": "string"
}

Response samples

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

Share Report

Shares a Report with the specified users and groups.

Authorizations:
APITokenOAuth2 (SHARE_SHEETS)
path Parameters
reportId
required
number

reportID of the report being accessed.

query Parameters
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 Report Shares

Gets a list of all users and groups to whom the specified Report is shared, and their access level. This operation supports query string parameters for pagination of results.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
reportId
required
number

reportID of the report being accessed.

query Parameters
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/reports/{reportId}/shares \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

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

Get Report Share

Gets the share specified in the URL.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
reportId
required
number

reportID of the report 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/reports/{reportId}/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 Report Share

Deletes the share specified in the URL.

Authorizations:
APITokenOAuth2 (SHARE_SHEETS)
path Parameters
reportId
required
number

reportID of the report 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/reports/{reportId}/shares/{shareId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

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

Update Report Share

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

Authorizations:
APITokenOAuth2 (SHARE_SHEETS)
path Parameters
reportId
required
number

reportID of the report 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 Related Items