Methods

Add Rows

Inserts one or more rows into the sheet specified in the URL. If you want to insert the rows in any position but the default, use location-specifier attributes (that is, toTop, toBottom, parentId, siblingId, above, indent, outdent). See language tabs for variations in syntax.

Note: This operation does not add rows with cells that have images. However, you can upload an image to a cell after the cell exists in a sheet. To do so, call the operation described in the Add Image to Cell page.

This operation supports both single-object and bulk semantics. For more information, see Optional Bulk Operations.

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

allowPartialSuccess
boolean
Default: false

When specified with a value of true, enables partial success for this bulk operation. See Partial Success for more information.

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.

Request Body schema: application/json

Row object or an array of Row objects, with the following attributes:

  • One or more location-specifier attributes (required)
  • expanded (optional)
  • format (optional)
  • cells (optional) -- if specified, must be an array of Cell objects, where each object is limited to the following attributes:
    • columnId (required)
    • One of the following (required):
      • formula: the formula for the cell. For cross-sheet formulas, you must first define a cross-sheet reference
      • value
    • When value is specified
      • hyperlink (optional) with exactly one of the following attributes set:
        • reportId
        • sheetId
        • url
      • linkInFromCell (optional) with all of the following attributes set:
        • columnId
        • rowId
        • sheetId
      • strict (optional)
    • format (optional)
    • overrideValidation (optional)
  • locked (optional) - true to lock the row or false to unlock the row. See Column Types for more information.

NOTES:

  • Column Ids must be valid for the sheet to which the row belongs, and must only be used once for each row in the operation.
  • Cells of a project sheet in the "Finish Date" column cannot be updated via API.
  • Cells of a project sheet in the "Start Date" column cannot be updated via API for rows that contain a value in the "Predecessor" column.
  • Max length for a cell value is 4000 characters after which truncation occurs without warning. Empty string values are converted to null.
  • When adding or updating rows, there is a 500 row limit for each API call.
  • Calculation errors or problems with a formula do not cause the API call to return an error code. Instead, the response contains the same value as in the UI, such as cell.value = "#CIRCULAR REFERENCE".
  • If you are adding or updating a row using linkInFromCell, you cannot use overrideValidation as a query param. In this case, you must pass overrideValidation in the body as a cell update field. Additionally, linkInFromCell requires a value of null.
  • Any one sheet can have up to 500,000 inbound cell links. (Smartsheet Gov has an inbound cell link limit of 100,000.)
  • If you want to clear a cell link, you can either pass value as an empty string or set the value to the current value and omit linkInFromCell.
One of
id
number

Row Id.

sheetId
number

Parent sheet Id.

siblingId
number

Sibling Id.

accessLevel
string
Enum: "ADMIN" "COMMENTER" "EDITOR" "EDITOR_SHARE" "OWNER" "VIEWER"
Array of objects

Attachments on row. Only returned if the include query string parameter contains attachments.

Array of objects

Cells belonging to the row.

Array of objects

Columns of row. Only returned if the include query string parameter contains columns.

conditionalFormat
string

Describes this row's conditional format. Only returned if the include query string parameter contains format and this row has a conditional format applied.

object

User object containing name and email of the creator of this row.

Array of objects

Discussions on the row. Only returned if the include query string parameter contains discussions.

object

Object containing zero or more media items, including images, videos, and documents, for review, editing, or approval.

expanded
boolean

Indicates whether the row is expanded or collapsed.

filteredOut
boolean

Indicates if the row is filtered out by a column filter. Only returned if the include query string parameter contains filters.

format
string

Format descriptor. Only returned if the include query string parameter contains format and this row has a non-default format applied.

inCriticalPath
boolean

Only returned, with a value of true, if the sheet is a project sheet with dependencies enabled and this row is in the critical path.

locked
boolean

Indicates whether the row is locked.

lockedForUser
boolean

Indicates whether the row is locked for the requesting user.

object

User object containing name and email of the last person to modify this row.

permaLink
string

URL that represents a direct link to the row in Smartsheet. Only returned if the include query string parameter contains rowPermalink.

rowNumber
number >= 1

Row number within the sheet.

version
number

Sheet version number that is incremented every time a sheet is modified.

Responses

Request samples

Content type
application/json
[ ]

Response samples

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

Delete Rows

Deletes one or more rows from the sheet specified in the URL.

Authorizations:
APITokenOAuth2 (WRITE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
ids
required
string

A comma-separated list of row Ids.

ignoreRowsNotFound
boolean
Default: false

true or false. If set to false and any of the specified row Ids are not found, no rows are deleted, and the "not found" error is returned.

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}/rows?ids={rowId1},{rowId2},{rowId3}&ignoreRowsNotFound=true' \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

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

Update Rows

Updates cell values in the specified rows, expands/collapses the specified rows, or modifies the position of specified rows (including indenting/outdenting). For detailed information about changing row positions, see location-specifier attributes.

Note: This operation does not handle adding images to cells. However, you can upload an image to a cell by calling the operation described in the Add Image to Cell page.

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

allowPartialSuccess
boolean
Default: false

When specified with a value of true, enables partial success for this bulk operation. See Partial Success for more information.

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.

Request Body schema: application/json

Row object or an array of Row objects, with the following attributes:

  • id (required)
  • One or more location-specifier attributes (optional)
  • expanded (optional)
  • format (optional)
  • cells (optional) -- if specified, must be an array of Cell objects, where each object is limited to the following attributes:
    • columnId (required)
    • One of the following (required):
      • formula: the formula for the cell. For cross-sheet formulas, you must first define a cross-sheet reference
      • value
    • When value is specified
      • hyperlink (optional) with exactly one of the following attributes set:
        • reportId
        • sheetId
        • url
      • linkInFromCell (optional) with all of the following attributes set:
        • columnId
        • rowId
        • sheetId
      • strict (optional)
    • format (optional)
    • image (optional) -- object for setting a cell image's attributes, such as its alternate text (e.g., altText = string).
    • overrideValidation (optional)
  • locked (optional) - true to lock the row or false to unlock the row. See Column Types for more information.

NOTE:

  • Column Ids must be valid for the sheet to which the row belongs, and must only be used once for each row in the operation.
  • Cells of a project sheet in the "Finish Date" column cannot be updated via API.
  • Cells of a project sheet in the "Start Date" column cannot be updated via API for rows that contain a value in the "Predecessor" column.
  • Max length for a cell value is 4000 characters after which truncation occurs without warning. Empty string values are converted to null.
  • Calculation errors or problems with a formula do not cause the API call to return an error code. Instead, the response contains the same value as in the UI, such as cell.value = "#CIRCULAR REFERENCE".
One of
id
number

Row Id.

sheetId
number

Parent sheet Id.

siblingId
number

Sibling Id.

accessLevel
string
Enum: "ADMIN" "COMMENTER" "EDITOR" "EDITOR_SHARE" "OWNER" "VIEWER"
Array of objects

Attachments on row. Only returned if the include query string parameter contains attachments.

Array of objects

Cells belonging to the row.

Array of objects

Columns of row. Only returned if the include query string parameter contains columns.

conditionalFormat
string

Describes this row's conditional format. Only returned if the include query string parameter contains format and this row has a conditional format applied.

object

User object containing name and email of the creator of this row.

Array of objects

Discussions on the row. Only returned if the include query string parameter contains discussions.

object

Object containing zero or more media items, including images, videos, and documents, for review, editing, or approval.

expanded
boolean

Indicates whether the row is expanded or collapsed.

filteredOut
boolean

Indicates if the row is filtered out by a column filter. Only returned if the include query string parameter contains filters.

format
string

Format descriptor. Only returned if the include query string parameter contains format and this row has a non-default format applied.

inCriticalPath
boolean

Only returned, with a value of true, if the sheet is a project sheet with dependencies enabled and this row is in the critical path.

locked
boolean

Indicates whether the row is locked.

lockedForUser
boolean

Indicates whether the row is locked for the requesting user.

object

User object containing name and email of the last person to modify this row.

permaLink
string

URL that represents a direct link to the row in Smartsheet. Only returned if the include query string parameter contains rowPermalink.

rowNumber
number >= 1

Row number within the sheet.

version
number

Sheet version number that is incremented every time a sheet is modified.

Responses

Request samples

Content type
application/json
[ ]

Response samples

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

Send Rows via Email

Sends one or more rows via email.

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

The columns included for each row in the email are populated according to the following rules:

  • If the columnIds attribute of the MultiRowEmail object is specified as an array of column Ids, those specific columns are included.
  • If the columnIds attribute of the MultiRowEmail object is omitted, all columns except hidden columns shall be included.
  • If the columnIds attribute of the MultiRowEmail object is specified as empty, no columns shall be included. (NOTE: In this case, either includeAttachments=true or includeDiscussions=true must be specified.)
rowIds
Array of numbers

The Ids of rows to be included.

columnIds
Array of numbers

The Id of the columns to be included.

includeAttachments
boolean

Indicates whether to include attachments in the email.

includeDiscussions
boolean

Indicates whether to include discussions in the email.

layout
boolean

One of the following values: HORIZONTAL or VERTICAL. Optional, defaults to HORIZONTAL when multiple rows are being sent and to VERTICAL when a single row is being sent. HORIZONTAL formats the rows being sent as a grid, whereas VERTICAL formats the rows being sent as separate cards.

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
{
  • "rowIds": [
    ],
  • "columnIds": [
    ],
  • "includeAttachments": true,
  • "includeDiscussions": true,
  • "layout": true,
  • "ccMe": true,
  • "message": "string",
  • "sendTo": [
    ],
  • "subject": "string"
}

Response samples

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

Copy Rows to Another Sheet

Copies rows from the sheet specified in the URL to (the bottom of) another sheet.

Authorizations:
APITokenOAuth2 (WRITE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
include
string

A comma-separated list of row elements to copy in addition to the cell data:

  • all - specify a value of all to include everything (attachments, children, and discussions).
  • attachments
  • children - if specified, any child rows of the rows specified in the request are also copied to the destination sheet, and parent-child relationships amongst rows are preserved within the destination sheet; if not specified, only the rows specified in the request are copied.
  • discussions
Enum: "all" "attachments" "children" "discussions"
ignoreRowsNotFound
boolean
Default: false

true or false: default is false. If set to true, specifying row Ids that do not exist within the source sheet does not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet causes an error response (and no rows are copied).

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
rowIds
Array of numbers

The Ids of the rows to move or copy from the source sheet.

object

Responses

Request samples

Content type
application/json
{
  • "rowIds": [
    ],
  • "to": {
    }
}

Response samples

Content type
application/json
{
  • "destinationSheetId": 0,
  • "rowMappings": [
    ]
}

Move Rows to Another Sheet

Moves rows from the sheet specified in the URL to (the bottom of) another sheet.

Authorizations:
APITokenOAuth2 (WRITE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
include
string

A comma-separate list of row elements to move in addition to the cell data.

Enum: "attachments" "discussions"
ignoreRowsNotFound
boolean
Default: false

true or false: default is false. If set to true, specifying row Ids that do not exist within the source sheet does not cause an error response. If omitted or set to false, specifying row Ids that do not exist within the source sheet causes an error response (and no rows are moved).

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
rowIds
Array of numbers

The Ids of the rows to move or copy from the source sheet.

object

Responses

Request samples

Content type
application/json
{
  • "rowIds": [
    ],
  • "to": {
    }
}

Response samples

Content type
application/json
{
  • "destinationSheetId": 0,
  • "rowMappings": [
    ]
}

Get Row

Gets the row specified in the URL.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

rowId
required
number

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

See Row Include Flags.

Also supports the columns include flag, which adds a columns array that specifies all of the columns for the sheet. This enables you to have the full context of the cells in the row.

The filters include flag returns a filteredOut attribute indicating if the row should be displayed or hidden according to the sheet's filters.

Enum: "columns" "filters"
exclude
string

A comma-separated list of element types to exclude from 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 empty cells
Enum: "filteredOutRows" "linkInFromCellDetails" "linksOutToCellsDetails" "nonexistentCells"
level
integer
Default: 0

Specifies whether object data types, such as multi-contact data are returned in a backwards-compatible, text format in text/number columns.
- Set level=0 (default) to use text/number columns for multi-contact data and multi-picklist data.
- Set level=1 to use multiple-entry contact list columns for multi-contact data; multi-picklist data is returned in text/number columns.
- Set level=2 to use multiple-entry contact list columns for multi-contact data and use multiple-entry picklist columns for multi-picklist data.

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}/rows/{rowId}?include=discussions,attachments,columns,columnType' \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "id": 0,
  • "sheetId": 0,
  • "rowNumber": 1,
  • "expanded": true,
  • "cells": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "modifiedAt": "2019-08-24T14:15:22Z"
}

Sort Rows in Sheet

Sorts the rows of a sheet, either in ascending or descending order.

Authorizations:
APITokenOAuth2 (WRITE_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

query Parameters
include&exclude
string

(Optional) Any of the relevant parameters or query parameters listed for Get Sheet.

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

SortSpecifier with the following attribute:

  • sortCriteria -- SortCriterion array in priority order. Specifies sort order.
Array of objects

Specifies sort order. Array is in priority order.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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": {
    }
}
➔ Next to Related Items