Sheets, rows, columns, and cells

Sheets have a core hierarchy of Sheet > Column > Row > Cell. The strict hierarchy tells you how to associate the objectId with the object. For example, your return might include a Sheet object with many Row objects. Each object has an objectId. The strict hierarchy helps you map the objectId to the sheet or specific row.

Cells are a little different. You identify a cell by its location in the grid, so you need both a column Id and a row Id to pinpoint a specific cell. The following table defines these terms and points you to places in this documentation where you can find more information:

Sheet Responses

Many Smartsheet API operations handle sheets, rows, columns, and cells. Each is identified by an Id and it is important to understand the relationship between these objects. Typically you loop through the columns to determine the Id of the columns you are interested in. Then you loop through the rows and contained cells to find actual values. The annotated sample response below illustrates these concepts by calling a very simple sheet called "Employee Roster".

Before you begin, you should already have an access token, which you used in the exercise above. Use the same access token for this walkthrough.

Step 1: The first thing you must have is a sheetId. To find a sheetId through the UI, with the sheet open, click "Sheet Actions" in the left toolbar and select "Properties". NOTE: use List Sheets if you want to do this programmatically.

Step 2: Copy the sheetId into the API call, GET /sheets, as below:

curl -X GET -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" "https://api.smartsheet.com/2.0/sheets/6141831453927300"

Step 3: The sample request and response are displayed below. NOTE: while JSON doesn't have a comment feature, this sample uses comments to help you identify the objects in the response.

{
"id": 6141831453927300,    // Sheet Id
"name": "My first sheet",
"columns": [{              // Each Column object associates column Id
                            // to title and defines the
                            // column details

        "id": 2517104256673668,   // Column Id
        "index": 0,
        "title": "Name",
        "type": "TEXT_NUMBER",
        "primary": true,
        "width": 150
    },
    {
        "id": 7020703884044164,   // Next column Id
        "index": 1,
        "title": "EmployeeId",
        "type": "TEXT_NUMBER",
        "width": 150
    }
],
"rows": [{                       // A Row object
        "id": 564480076736388,    // Row Id
        "rowNumber": 1,
        "expanded": true,
        "createdAt": "2017-05-12T16:52:38Z",
        "modifiedAt": "2017-05-22T20:40:14Z",
        "cells": [{  // Each row contains an array of cells,
                    // which have the actual content

                    "columnId": 2517104256673668,
                    // The column Id can be interpreted by
                    // looking at the array of column
                    // definitions above. That tells you
                    // this is the "Name" column

                    "value": "John Doe",
                    "displayValue": "John Doe"
                    },
                    {
                    "columnId": 7020703884044164,
                    "value": 12345,            // Actual cell value
                    "displayValue": "12,345"
                    // How the cell value is displayed in the UI
                    }
        ]},
        {
        "id": 5068079704106884,
        "rowNumber": 2,
        "siblingId": 564480076736388,
        "expanded": true,
        "createdAt": "2017-05-12T16:52:38Z",
        "modifiedAt": "2017-05-22T20:40:14Z",
        "cells": [{
                    "columnId": 2517104256673668,
                    "value": "Jane Roe",
                    "displayValue": "Jane Roe"
                    },
                    {
                    "columnId": 7020703884044164,
                    "value": 67890,
                    "displayValue": "67890"
                    }
        ]
        }
]
}

This core hierarchy of Sheet > Column > Row > Cell is essential to working with the Smartsheet API. As your user's sheets grow in complexity, the responses do too. This walkthrough has given you some navigational aid in finding the right value to plug into your API calls. Use the API Reference and the example language tabs to learn more.

Sheet filters

You cannot create or update filters using the API; however, you can query which rows have been filtered out and you can get filter definitions.

For details, see Filters object.

Cell formulas

Formulas are processed per cell in the UI. Use the Cell object to manipulate formulas via the API.

For requests, use Update Rows to add or update the formula in a cell.

For response payloads, formulas (when present) are returned whenever the Cell object is returned, so for example, GET /sheets/(id) returns the Cell object for each cell and that object contains a formula value when the cell contains a formula.