Skip to content
/Basics
Last updated

Basics

The Smartsheet API serves as a powerful bridge for you to interact with Smartsheet’s core features, enabling automated workflows and data integration across platforms. Understanding these foundational basics—ranging from authentication and URL structures to data handling and limitations—is essential for building robust, secure, and efficient applications.

Articles in this section:

  • Authentication This guide explains how to secure your API requests using access tokens generated within the Smartsheet UI. It details the requirement of including these tokens as a Bearer value in the Authorization header for every call to ensure authorized access to organizational resources.

  • Base URL This article outlines the structure of Smartsheet API endpoints, consisting of a secure scheme (HTTPS), specific product host (such as api.smartsheet.com), and the versioned base path. It provides specific URLs for different regional instances, including Smartsheet Gov and Smartsheet Regions.

  • Dates and Times Smartsheet standardizes time data by returning all dates and times in UTC using the ISO-8601 format. The guide also highlights the numericDates query parameter, which allows you to swap ISO strings for UNIX epoch milliseconds depending on your application's needs.

  • HTTP and REST This content covers the RESTful nature of the API, utilizing standard HTTP methods like GET, POST, PUT, and DELETE. It explains the resource-oriented URL structure and provides examples of how to perform CRUD operations on objects like sheets and rows.

  • Limitations To maintain system performance, Smartsheet imposes specific hard limits on data volume and request sizes. This article provides all the details.

  • Pagination This guide describes how the API manages large datasets by breaking them into manageable "pages." It details two primary strategies: token-based pagination (using lastKey) and offset-based pagination (using page and pageSize), both designed to reduce latency and memory consumption.

  • Pagination - SDK Examples Focusing on practical implementation, this guide provides code snippets for Python, Java, JavaScript, and C#. It demonstrates how to use Smartsheet SDKs to programmatically loop through paginated results using tokens to ensure complete data retrieval.

  • Resource Access Levels This summary clarifies the accessLevel attribute, which defines a user’s permissions for specific objects. It lists the various roles—such as OWNER, ADMIN, EDITOR, and VIEWER—and explains how these permissions mirror the sharing controls found in the standard Smartsheet UI.

  • Sheets, Rows, Columns, and Cells This article explores the hierarchical data structure of Smartsheet. It explains how sheets are composed of rows and columns, how cells store data and formatting, and how you can use optional "include" flags to fetch additional metadata like attachments or discussions.

  • Query Parameters This guide lists the various common parameters available to modify API behavior, such as include, exclude, and level. These parameters allow you to customize the depth and scope of the data returned, though the guide cautions that extensive use may impact response times.

  • Versioning and Changes Smartsheet details its approach to API evolution, emphasizing backward compatibility. It explains that while new features are added via "levels" to avoid breaking existing integrations, developers should design their code to handle new JSON properties and non-guaranteed object ordering gracefully.

Previous page
Next page