Smartsheet Python SDK

Warnings

• gotcha Authentication primarily relies on the `SMARTSHEET_ACCESS_TOKEN` environment variable for direct API access. For application development, OAuth 2.0 is supported but requires more setup. Misconfiguring or not setting the access token is a common source of 'Unauthorized' errors.
  Fix: Generate an API access token from your Smartsheet personal settings and set it as the `SMARTSHEET_ACCESS_TOKEN` environment variable. For OAuth, follow the official Smartsheet API documentation.
• gotcha By default, the SDK returns `Error` objects instead of raising exceptions for API errors. This can lead to silent failures if not handled correctly. Ensure you check the return type of API calls.
  Fix: Call `smartsheet_client.errors_as_exceptions(True)` after initializing your client to make the SDK raise `smartsheet.exceptions.SmartsheetException` instances for API errors, allowing for standard Python exception handling.
• breaking Smartsheet API endpoints are periodically updated or deprecated. Older SDK versions might not support new endpoints or parameters, leading to unexpected behavior or `AttributeError` if attempting to call non-existent methods.
  Fix: Always keep the `smartsheet-python-sdk` up-to-date (`pip install --upgrade smartsheet-python-sdk`). Consult the `CHANGELOG.md` in the GitHub repository for breaking changes and new endpoint support.
• gotcha Many list operations (e.g., listing sheets, rows, contacts) are paginated by default. If you need all results, you must either explicitly pass `include_all=True` to the list method or implement manual pagination using `page` and `page_size` parameters.
  Fix: When calling list methods, review the documentation for pagination parameters. Use `include_all=True` for convenience, or loop through `page` and `page_size` for fine-grained control.
• gotcha Accessing model creation methods (e.g., for Sheet, Column, Row objects) directly from `smartsheet.Smartsheet.models.ClassName` instead of using the methods on the instantiated service objects (e.g., `smart.Sheets.add_sheet()`) or correctly creating model instances, can lead to `AttributeError`.
  Fix: When creating or manipulating objects, ensure you're using the correct methods on the client's service objects (e.g., `smart.Sheets.create_sheet()`) or correctly instantiating model classes with `smartsheet.Smartsheet.models.Sheet({'name': 'New Sheet'})` before passing them to service methods.

Install

• pip install smartsheet-python-sdk Install latest version

Imports

• Smartsheet

  import smartsheet
  smart = smartsheet.Smartsheet()

  The primary client class for interacting with the Smartsheet API.
• models

  import smartsheet
  sheet_obj = smartsheet.Smartsheet.models.Sheet()

  Model classes like Sheet, Column, Row, etc., are accessed through `smartsheet.Smartsheet.models`.

Quickstart

This quickstart initializes the Smartsheet client using an API access token from environment variables. It then lists the user's sheets and retrieves details for the first one found. It also demonstrates how to enable exceptions for API errors.

import smartsheet
import os

# Ensure SMARTSHEET_ACCESS_TOKEN is set in your environment variables
# You can generate an access token in Smartsheet UI under Account > Personal Settings > API Access.
access_token = os.environ.get('SMARTSHEET_ACCESS_TOKEN', '')

if not access_token:
    print("Error: SMARTSHEET_ACCESS_TOKEN environment variable not set.")
    print("Please generate an access token from Smartsheet and set it.")
else:
    try:
        # Create a Smartsheet client
        smart = smartsheet.Smartsheet(access_token)

        # Optional: Enable exceptions for API errors instead of returning Error objects
        smart.errors_as_exceptions(True)

        # List all sheets the authenticated user has access to
        response = smart.Sheets.list_sheets()

        if response.data:
            first_sheet = response.data[0]
            print(f"Found sheet: {first_sheet.name} (ID: {first_sheet.id})")
            
            # Get a specific sheet by ID
            sheet = smart.Sheets.get_sheet(first_sheet.id)
            print(f"The sheet '{sheet.name}' has {sheet.total_row_count} rows.")
        else:
            print("No sheets found for this user.")

    except smartsheet.exceptions.SmartsheetException as e:
        print(f"An error occurred: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")