Smartsheet logo

Methods

List Columns

Gets a list of all columns belonging to the sheet specified in the URL.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

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

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.

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).

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

Response samples

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

Add Columns

Inserts one or more columns into the sheet specified in the URL.This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment.

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

A Column object that contains the following attributes

  • title

  • type

  • formula (optional)

  • index (zero-based)

  • autoNumberFormat (optional)

  • description (optional)

  • locked(optional)

  • options (optional)

  • symbol (optional)

  • systemColumnType (optional)

  • validation (optional)

  • width (optional)

    NOTES:

  • When setting a column type of PICKLIST or MULTI_PICKLIST, you must follow a one operation per API call rule. For these column types, you must set the column type first, and then add any additional constraints in a second call, such as setting validation to true.

  • When creating more than one column at a time, you cannot designate multiple index locations. Use one common index as the starting point. For example, designate the primary column as "1".

title
string

Column title.

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

The formula for a column, if set, for instance =data@row.

hidden
boolean

Indicates whether the column is hidden.

index
number

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

object

Object that describes how the the System Column type of "AUTO_NUMBER" is auto-generated.

object
description
string

Column description.

format
string

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

locked
boolean

Indicates whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin.

lockedForUser
boolean

Indicates whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.

options
Array of strings
symbol
string

When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns.

systemColumnType
string
Enum: "AUTO_NUMBER" "CREATED_BY" "CREATED_DATE" "MODIFIED_BY" "MODIFIED_DATE"
validation
boolean

Indicates whether validation has been enabled for the column (value = true)

version
number

Read only. The level of the column type. Each element in the array is set to one of the following values:

  • 0: TEXT_NUMBER, CONTACT_LIST, or PICKLIST
  • 1: MULTI_CONTACT_LIST
  • 2: MULTI_PICKLIST

See Versioning and Changes.

width
number

Display width of the column in pixels.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "type": "ABSTRACT_DATETIME",
  • "formula": "string",
  • "hidden": true,
  • "index": 0,
  • "autoNumberFormat": {
    },
  • "contactOptions": {
    },
  • "description": "string",
  • "format": "string",
  • "locked": true,
  • "lockedForUser": true,
  • "options": [
    ],
  • "symbol": "string",
  • "systemColumnType": "AUTO_NUMBER",
  • "validation": true,
  • "version": 0,
  • "width": 0
}

Response samples

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

Get Column

Gets definitions for the column specified in the URL. NOTE: If you need to see the values of individual cells within the column, use Get Sheet or Get Row.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

columnId
required
number

Column Id in the sheet being accessed.

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

Response samples

Content type
application/json
{
  • "id": 0,
  • "index": 0,
  • "symbol": "string",
  • "title": "string",
  • "type": "ABSTRACT_DATETIME",
  • "validation": true
}

Delete Column

Deletes the column specified in the URL.

Authorizations:
APITokenOAuth2 (ADMIN_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

columnId
required
number

Column Id in the sheet 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/sheets/{sheetId}/columns/{columnId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

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

Update Column

Updates properties of the column, moves the column, or renames the column.

NOTE:

  • You cannot change the type of a Primary column.
  • While dependencies are enabled on a sheet, you can't change the type of any special calendar/Gantt columns.
  • If the column type is changed, all cells in the column are converted to the new column type and column validation is cleared.
  • Type is optional when moving or renaming, but required when changing type or dropdown values.
Authorizations:
APITokenOAuth2 (ADMIN_SHEETS)
path Parameters
sheetId
required
number

Sheet Id of the sheet being accessed.

columnId
required
number

Column Id in the sheet being accessed.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json

A Column object that contains the following attributes:

  • index
  • autoNumberFormat (optional)
  • contactOptions (optional) -- must have set column type to CONTACT_LIST
  • description (optional)
  • format (optional)
  • formula (optional)
  • hidden(optional)
  • locked (optional)
  • options (optional)
  • symbol (optional)
  • systemColumnType (optional)
  • title (optional)
  • type (optional)
  • validation (optional)
  • width (optional)

NOTE: When setting a column type of PICKLIST or MULTI_PICKLIST, you must follow a one operation per API call rule. For these column types, you must set the column type first, and then add any additional constraints in a second call, such as setting validation to true.

title
string

Column title.

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

The formula for a column, if set, for instance =data@row.

hidden
boolean

Indicates whether the column is hidden.

index
number

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

object

Object that describes how the the System Column type of "AUTO_NUMBER" is auto-generated.

object
description
string

Column description.

format
string

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

locked
boolean

Indicates whether the column is locked. In a response, a value of true indicates that the column has been locked by the sheet owner or the admin.

lockedForUser
boolean

Indicates whether the column is locked for the requesting user. This attribute may be present in a response, but cannot be specified in a request.

options
Array of strings
symbol
string

When applicable for CHECKBOX or PICKLIST column types. See Symbol Columns.

systemColumnType
string
Enum: "AUTO_NUMBER" "CREATED_BY" "CREATED_DATE" "MODIFIED_BY" "MODIFIED_DATE"
validation
boolean

Indicates whether validation has been enabled for the column (value = true)

version
number

Read only. The level of the column type. Each element in the array is set to one of the following values:

  • 0: TEXT_NUMBER, CONTACT_LIST, or PICKLIST
  • 1: MULTI_CONTACT_LIST
  • 2: MULTI_PICKLIST

See Versioning and Changes.

width
number

Display width of the column in pixels.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "type": "ABSTRACT_DATETIME",
  • "formula": "string",
  • "hidden": true,
  • "index": 0,
  • "autoNumberFormat": {
    },
  • "contactOptions": {
    },
  • "description": "string",
  • "format": "string",
  • "locked": true,
  • "lockedForUser": true,
  • "options": [
    ],
  • "symbol": "string",
  • "systemColumnType": "AUTO_NUMBER",
  • "validation": true,
  • "version": 0,
  • "width": 0
}

Response samples

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