Smartsheet logo

Methods

Get Sheet Summary

Returns object containing array of summary fields. Allows for pagination of results.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
include
string

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

  • format: includes format info for cells, rows, and summary fields
  • writerInfo: includes createdBy and modifiedBy attributes for rows and summary fields
Enum: "format" "writerInfo"
exclude
string

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

  • displayValue: excludes displayValue info for cells, rows, and summary fields
  • image: excludes image attributes for cells and summary fields
  • imageAltText: excludes alt text for cells and summary fields
Enum: "displayValue" "image" "imageAltText"
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}/summary?include=writerInfo \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "fields": [
    ]
}

Get Summary Fields

Returns object containing array of summary fields. Allows for pagination of results.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

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, the last page of results is returned.

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 elements to include in the response.

  • format: includes format info for cells, rows, and summary fields
  • writerInfo: includes createdBy and modifiedBy attributes for rows and summary fields
Enum: "format" "writerInfo"
exclude
string

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

  • displayValue: excludes displayValue info for cells, rows, and summary fields
  • image: excludes image attributes for cells and summary fields
  • imageAltText: excludes alt text for cells and summary fields
Enum: "displayValue" "image" "imageAltText"
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}/summary/fields \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

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

Update Summary Fields

Updates the summary fields for the given sheet.

Authorizations:
APITokenOAuth2 (ADMIN_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
renameIfConflict
boolean
Default: false

Set to true if you want to override the requirement for unique summary field names. Repeated names will be adjusted by appending "(1)" or similar after the field name.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json

Array of SummaryField objects

Array ()
id
number

SummaryField Id.

Array of objects

Array of ContactOption objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST.

format
string

The format descriptor. Only returned if the include query string parameter contains format and this column has a non-default format applied to it.

formula
string

The formula for a cell, if set.

object
object
index
number

Field index or position. This number is zero-based.

locked
boolean

Indicates whether the field is locked.

AbstractDatetimeObjectValue (object) or CheckboxObjectValue (object) or ContactObjectValue (object) or DateObjectValue (object) or DatetimeObjectValue (object) or DurationObjectValue (object) or MultiContactObjectValue (object) or MultiPicklistObjectValue (object) or PredecessorListObjectValue (object)

The base object for values found in the Cell.objectValue attribute. Its objectType attribute indicates the type of the object. This object itself is not used directly.

options
Array of strings

When applicable for PICKLIST column type. Array of the options available for the field.

symbol
string

When applicable for PICKLIST column type.

title
string

Arbitrary name, must be unique within summary.

type
string
Enum: "ABSTRACT_DATETIME" "CHECKBOX" "CONTACT_LIST" "DATE" "DATETIME" "DURATION" "MULTI_CONTACT_LIST" "MULTI_PICKLIST" "PICKLIST" "PREDECESSOR" "TEXT_NUMBER"
validation
boolean

Indicates whether summary field values are restricted to the type.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Delete Summary Fields

Deletes summary fields from the specified sheet.

Authorizations:
APITokenOAuth2 (ADMIN_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
ids
required
string

A comma-separated list of Sheet Summary Field Ids.

ignoreSummaryFieldsNotFound
boolean
Default: false

If true, the operation will succeed even if some fieldIds are not found.

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}/summary/fields?ids={fieldId1},{fieldId2},{fieldId3} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

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

Add Summary Fields

Creates one or more summary fields for the specified sheet.

Authorizations:
APITokenOAuth2 (ADMIN_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
renameIfConflict
boolean
Default: false

Set to true if you want to override the requirement for unique summary field names. Repeated names will be adjusted by appending "(1)" or similar after the field name.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json

Array of SummaryField objects

Array ()
Array of objects

Array of ContactOption objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST.

format
string

The format descriptor. Only returned if the include query string parameter contains format and this column has a non-default format applied to it.

formula
string

The formula for a cell, if set.

object
object
index
number

Field index or position. This number is zero-based.

locked
boolean

Indicates whether the field is locked.

AbstractDatetimeObjectValue (object) or CheckboxObjectValue (object) or ContactObjectValue (object) or DateObjectValue (object) or DatetimeObjectValue (object) or DurationObjectValue (object) or MultiContactObjectValue (object) or MultiPicklistObjectValue (object) or PredecessorListObjectValue (object)

The base object for values found in the Cell.objectValue attribute. Its objectType attribute indicates the type of the object. This object itself is not used directly.

options
Array of strings

When applicable for PICKLIST column type. Array of the options available for the field.

symbol
string

When applicable for PICKLIST column type.

title
string

Arbitrary name, must be unique within summary.

type
string
Enum: "ABSTRACT_DATETIME" "CHECKBOX" "CONTACT_LIST" "DATE" "DATETIME" "DURATION" "MULTI_CONTACT_LIST" "MULTI_PICKLIST" "PICKLIST" "PREDECESSOR" "TEXT_NUMBER"
validation
boolean

Indicates whether summary field values are restricted to the type.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Add Image to Sheet Summary

Adds an image to the summary field.

Authorizations:
APITokenOAuth2 (WRITE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

fieldId
required
number

Summary Field Id of the sheet summary field being accessed.

query Parameters
altText
string

Url-encoded alternate text for the image

overrideValidation
boolean
Default: false

You may use the query string parameter overrideValidation with a value of true to allow a cell value outside of the validation limits. You must specify strict with a value of false to bypass value type checking.

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.

Content-Disposition
string

Should be equal to "attachment" 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

Example: attachment; filename="ProgressReport.docx"
Content-Length
integer

Must 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

Example: 5463
Request Body schema: application/octet-stream
string <binary>

Responses

Request samples 

curl https://api.smartsheet.com/2.0/sheets/{sheetId}/summary/fields/{fieldId}/images?altText=my%20image \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-H "Content-Type: image/jpeg" \
-H 'Content-Disposition: attachment; filename="picture.jpg"' \
-X POST \
--data-binary @picture.jpg

Response samples

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