Smartsheet Getting Started: API Integration & First Request

Getting started overview

Integrating with Smartsheet's API allows for programmatic management of sheets, rows, columns, and other Smartsheet assets. This guide outlines the steps to create an account, obtain an API access token, and execute a foundational API request. The Smartsheet API uses RESTful principles and OAuth 2.0 for authentication, enabling secure interactions with user data.

Before initiating API calls, users typically establish a Smartsheet account, which provides access to the web application and the necessary administrative features for API token generation. The API supports various operations, including creating, reading, updating, and deleting sheet data, as well as managing workspaces and reports. For detailed API specifications, refer to the official Smartsheet API documentation.

Quick reference steps

The following table provides a summary of the initial steps to get started with the Smartsheet API:

Create an account and get keys

Accessing the Smartsheet API requires an active Smartsheet account. If you do not have one, you can sign up for a Smartsheet free plan, which supports a single user, or choose a paid plan for collaborative features. Once your account is established, you will need to generate a personal access token, which serves as your API key for authentication.

Account creation

1. Navigate to the Smartsheet website.
2. Select a plan (Free, Pro, Business, or Enterprise) and complete the registration process.
3. Verify your email address to activate your account.

Generate an API access token

The Smartsheet API uses personal access tokens for authentication. These tokens are bearer tokens that grant access to your Smartsheet data. It is crucial to treat these tokens like passwords and secure them appropriately, as they provide full access to your account's permissions.

1. Log in to your Smartsheet account.
2. Click on your profile icon in the bottom left corner and select Personal Settings.
3. In the Personal Settings dialog, click on API Access.
4. Click Generate new access token.
5. Provide a name for your token (e.g., "API Integration") and click OK.
6. Copy the generated token immediately. This token will only be displayed once. If you lose it, you will need to generate a new one.

For applications requiring more robust authentication or user consent, Smartsheet also supports OAuth 2.0. OAuth 2.0 is a common framework for delegated authorization, allowing third-party applications to obtain limited access to a user's resources without exposing their credentials. For more on OAuth 2.0, refer to the IETF RFC 6749 specification.

Your first request

After obtaining your API access token, you can make your first API call. A common initial request is to list all sheets associated with your account. This confirms that your authentication is set up correctly and provides a basic understanding of the API's response structure.

This example uses cURL, a command-line tool for making HTTP requests, which is widely available on most operating systems. Replace YOUR_ACCESS_TOKEN with the token you generated.

API Endpoint for Listing Sheets

The endpoint for listing all sheets is https://api.smartsheet.com/2.0/sheets.

cURL example

curl -X GET \
  'https://api.smartsheet.com/2.0/sheets' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Explanation:

• -X GET specifies the HTTP GET method.
• 'https://api.smartsheet.com/2.0/sheets' is the API endpoint.
• -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' sends your access token in the Authorization header, as required by OAuth 2.0 bearer token authentication.
• -H 'Content-Type: application/json' indicates that the request body (if any) is JSON, though for a GET request, this is often less critical.
• -H 'Accept: application/json' requests the response in JSON format.

Expected Response

A successful response (HTTP status 200 OK) will return a JSON object containing an array of sheet objects. Each sheet object will include properties like id, name, permalink, and other metadata. If you have no sheets, the data array within the response will be empty.

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalCount": 2,
  "data": [
    {
      "id": 1234567890123456,
      "name": "My First Sheet",
      "permalink": "https://app.smartsheet.com/b/home?lx=abcdefg",
      "createdAt": "2023-01-01T12:00:00Z",
      "modifiedAt": "2023-01-01T12:00:00Z"
    },
    {
      "id": 9876543210987654,
      "name": "Project Tracking",
      "permalink": "https://app.smartsheet.com/b/home?lx=hijklmn",
      "createdAt": "2023-02-15T09:30:00Z",
      "modifiedAt": "2023-02-15T09:30:00Z"
    }
  ]
}

Common next steps

Once you have successfully made your first API call, you can explore more advanced functionalities of the Smartsheet API:

• Use an SDK: Smartsheet provides SDKs for popular programming languages like Java, C#, Python, and Node.js. Using an SDK can simplify API interactions by handling authentication, request formatting, and response parsing. Refer to the Smartsheet SDK documentation for setup instructions.
• Create and Update Sheets: Learn to programmatically create new sheets, add rows and columns, and update existing cell data. These operations are fundamental for automated data management.
• Webhooks: Implement webhooks to receive real-time notifications about changes in your Smartsheet data. This can trigger automated workflows in other systems. The Smartsheet Webhooks guide provides implementation details.
• Error Handling: Understand how to interpret API error codes and messages to build robust integrations. The API returns standard HTTP status codes and detailed JSON error bodies.
• Rate Limits: Be aware of Smartsheet's API rate limits to prevent your application from being throttled. The Smartsheet API overview describes these limits.
• OAuth 2.0 for Production: For public applications or those requiring user consent, transition from personal access tokens to OAuth 2.0 for more secure and scalable authentication.
• Explore Advanced Features: Investigate features like reports, dashboards, and resource management through the API to build comprehensive solutions.

Troubleshooting the first call

If your first API call does not return the expected results, consider the following common issues and troubleshooting steps:

• Incorrect Access Token: Ensure the YOUR_ACCESS_TOKEN placeholder in the cURL command is replaced with your actual, unexpired personal access token. Double-check for extra spaces or incorrect characters. If in doubt, generate a new token.
• Missing Authorization Header: The Authorization: Bearer YOUR_ACCESS_TOKEN header is mandatory. Without it, the API will return an authentication error, typically an HTTP 401 Unauthorized status.
• Network Connectivity: Verify your internet connection. Proxy settings or firewalls might block outgoing requests.
• Endpoint Typos: Ensure the API endpoint URL (https://api.smartsheet.com/2.0/sheets) is spelled correctly.
• HTTP Method: Confirm you are using the correct HTTP method (GET for listing sheets). Using an incorrect method will result in an HTTP 405 Method Not Allowed error.
• JSON Parsing Errors: If you receive a response but cannot parse it, ensure your JSON parser is configured correctly. The Smartsheet API typically returns valid JSON.
• Rate Limiting: While unlikely for a first call, repeated failed attempts in a short period might trigger rate limiting, resulting in an HTTP 429 Too Many Requests status. Wait a few minutes before retrying.
• Smartsheet Account Status: Confirm your Smartsheet account is active and not suspended.
• Refer to Developer Tools: Use browser developer tools (for web-based calls) or tools like Postman to inspect the full request and response, including headers and status codes, for more detailed error information.
• Check Official Documentation: The Smartsheet API overview and specific endpoint documentation provide details on expected request formats and common error responses.