Getting started with the Smartsheet API
Published on 04 February 2016
Looking to build an integration using the Smartsheet API, but not sure exactly where to start? Simply follow these five steps, and you’ll be up and running in no time!
Step 1: Explore Developer Resources
Step 2: Complete 'Developer Registration' (optional)
Step 3: Generate an Access Token
Step 4: Start building!
Step 5: Get support
Explore Developer Resources
The Smartsheet Developer Portal is the “home base” for all Developer Resources. There you’ll find answers to API FAQs, API documentation, information about Smartsheet SDKs, and more. As tempting as it may be to dive right into building your integration, investing the time up front to review these resources will pay dividends down the road.
If you’re brand new to the Smartsheet API, start by reviewing the API FAQs. This information provides some great high-level context for working with the Smartsheet API.
Once you’ve reviewed the FAQs, head on over to the API Documentation. Regardless of whether you’re planning to create an integration that accesses the API directly, or one that uses a Smartsheet SDK, the API docs contain lots of useful information. At a minimum, you should become familiar with the following sections:
Overview - sets high-level context for working with the Smartsheet API.
API Fundamentals - covers topics that are central to working with the Smartsheet API. Includes valuable information about API Best Practices and API Troubleshooting, along with important guidance related to Authentication, Rate Limiting, Error Handling, and more.
Getting Started - contains information that you’ll need to lay the groundwork for your integration.
Smartsheet SDKs provide a means of accessing the Smartsheet API via the language of your choice, without having to write all the code from scratch. Don’t see an SDK for your preferred language? Drop us a line so that we can consider it for future development!
**Complete 'Developer Registration' **(optional)
At this point, you’re familiar with Smartsheet Developer Resources and ready to lay the groundwork for creating your integration.
If you’re planning to build a third-party application OR if you want to create a sandbox Smartsheet account that you can use purely for development and testing purposes (without affecting data in your production Smartsheet account), you’ll need to complete the Developer Registration process.
If neither of the above scenarios apply to you -- because you’re planning to use the API to directly access data within your own Smartsheet account and don’t care to have a separate sandbox environment for dev/test -- you can skip the registration process altogether.
Generate an Access Token
Next, to authenticate API requests via Direct API Access, you’ll need an API access token that’s owned by the Smartsheet account that you want to access*. Access tokens are generated via the Smartsheet UI: simply login to your Smartsheet account, then follow the instructions here to generate a token.
*Note: Access tokens that are owned by a user who has System Admin rights in Smartsheet enable API functionality above and beyond that which is granted to ‘non-admin’ tokens. For more information, see the Admin Features section in the API docs.
If you’re building a third-party application that will implement the OAuth2 flow (to retrieve an access token that can be used to access Smartsheet data on behalf of an end user), then you won’t need to manually generate an access token as described above. Instead, consult the API docs for information about third-party app development.
Finally, time for the fun part -- building your integration! This process will vary depending on whether or not you choose to use an SDK.
Using an SDK
To use an SDK as the basis for your integration, install the SDK of your choice (by following instructions provided in the SDK’s Readme on GitHub). Then, leverage the API Documentation for code samples:
Using the panel on the right side of the page, select the tab for the language that you’re interested in.
Review the SDKs and Sample Code subsection for the language that you’re using, which provides information about connecting to Smartsheet and executing API operations using the SDK.
Navigate to any API Reference section to see a code sample that demonstrates how to execute the operation using the SDK.
*Note: SDKs tend to lag a bit behind the actual API in terms of functionality exposed. If an SDK doesn’t expose the API functionality you need, you might opt to download the SDK source from GitHub, add the missing functionality, then submit a pull request to ask that your changes be incorporated into the GitHub repository.
Not using an SDK
While using an SDK can streamline your integration project, it’s by no means mandatory. If you choose to forgo using an SDK in favor of building a custom integration from scratch, leverage the API Documentation as your primary resource:
Design and implement your integration in accordance with the API Best Practices.
Ensure that you have a solid understanding of API Fundamentals.
Leverage the API Reference section for detailed information about any API operation.
In an ideal world, your integration comes together magically, with no challenges along the way. But in the event that you experience otherwise, we’re here to help!
Encounter an API issue that you can’t resolve using the API Troubleshooting guidance, or have a question that’s not addressed by the API docs? Post your issue or question to StackOverflow, where we (along with thousands of developers worldwide) are standing by, ready to assist.
Have feedback about the API or want to suggest new API features? Drop us a line at firstname.lastname@example.org!
There’s inevitably a learning curve when using a new API for the first time, but the proper resources and process can make all the difference. We encourage you to accelerate the learning curve with the Smartsheet API by making the most of the resources and guidance that we’ve discussed in this post. In the meantime, we’re stoked to have you building upon the Smartsheet platform, and look forward to hearing from you if we can help along the way!