What we do
Tools
Industries
Department
How we workLet's talk →
Home/Smartsheet/Smartsheet API Documentation
Smartsheet

Smartsheet API documentation, cut down to what your first script needs

The official docs are thorough and spread across a lot of pages. These are the parts people go looking for first: the base URL for your region, the token, the plan you need, the rate limit, and the steps that get a sheet webhook switched on. SDKs exist for Python, JavaScript, Java and C#.

The essentials

Base URL: https://api.smartsheet.com/2.0. Accounts in Smartsheet Regions Europe use api.smartsheet.eu, Australia uses api.smartsheet.au, and Smartsheet Gov uses api.smartsheetgov.com. A token from one region won't work on another.

Token: generate it under your account, then send it as Authorization: Bearer <token>. It's shown once, so copy it straight away.

Account Personal Settings API Access Generate new access token

Plan: API access needs a Business, Enterprise or Advanced Work Management plan.

Rate limit: 300 requests a minute per token. Going over returns a 429 with error code 4003.

First call: GET /sheets lists the sheets the token can see. GET /sheets/{sheetId} returns one sheet with its columns and rows.

Getting a sheet webhook to fire

Smartsheet won't send a single event until your endpoint proves it's listening.

  1. 1

    Create the webhook

    POST /webhooks with a name, your callbackUrl, scope set to sheet, the sheet's ID as scopeObjectId, and the events you want (*.* for everything on that sheet). It's created disabled.

  2. 2

    Enable it

    Update the webhook with enabled: true. That's when Smartsheet sends a verification request to your callback URL.

  3. 3

    Answer the challenge

    The request carries a random value in the Smartsheet-Hook-Challenge header. Reply 200 and echo it back in a Smartsheet-Hook-Response header, or as smartsheetHookResponse in a JSON body.

    Watch for: this isn't a one-off. Smartsheet re-verifies once every 100 callbacks, and a failed check disables the webhook with the status DISABLED_VERIFICATION_FAILED.

  4. 4

    Check the signature

    Each callback is signed with the webhook's sharedSecret using SHA-256. Compute the HMAC of the raw body and compare it with the Smartsheet-Hmac-SHA256 header before trusting anything in it.

  5. 5

    Fetch what changed

    Callbacks are skinny: they say which row or cell changed and how, not what it now says. Use the IDs to call the API and read the current values.

How a sync spends 300 requests a minute

Most calls cost one request. A few cost ten, and bulk calls are your friend.

Example: one sync run against a 1,500-row sheet
Read the whole sheet (one GET returns columns and rows) 1
Add 400 new rows (one bulk POST, not 400 calls) 1
Update 200 changed rows (one bulk PUT) 1
Attach 6 files (attachments count as 10 each) 60
Cell history on 3 cells (also 10 each) 30
Used this minute 93 of 300

The same job written one row per call would need 600 requests for the rows alone and hit the limit inside the first minute. All workers sharing one token share the same 300.

Why a Smartsheet integration quietly stops

Columns looked up by their title

How you'll know: A column called "Due" became "Due date" and the script started skipping that field, or writing to the wrong one.

Fix: Store column IDs, which don't change on a rename. Re-read the column list at the start of each run and alert if a column you depend on has gone.

The webhook ran out of retries

How you'll know: The webhook's status is disabled and events stopped arriving after your server had an outage.

Fix: Smartsheet retries a failed delivery up to 14 times, the last ones about three hours apart, then disables the webhook. Watch the status, re-enable it, and re-read the sheet to catch what changed in the gap.

A token from the wrong region

How you'll know: Every call returns an authentication error, but the token works when someone tests it in another tool.

Fix: Check which host the account lives on. A Smartsheet Regions Europe token only works against api.smartsheet.eu.

An old notice applied as if it were new

How you'll know: A row flips back to a value someone changed an hour ago.

Fix: Retried callbacks can arrive hours late. Since the payload only names the row, always read its current values from the API before writing anywhere else.

One row at a time

How you'll know: 429 responses on large updates, and runs that take far longer than they should.

Fix: Send rows in bulk. A bulk add or update counts as one request against the limit.

Questions people ask

Does Smartsheet have an API, and which plans include it?

Yes, a REST API (version 2.0) covering sheets, rows, columns, attachments, reports and most of what you can do in the app. It needs a Business, Enterprise or Advanced Work Management plan.

Is there a Python SDK for Smartsheet?

Yes. Smartsheet publishes an official Python SDK, plus SDKs for JavaScript (Node.js), Java and C#. Each one handles authentication, request formatting and response parsing for you, and the source is on GitHub.

Does Smartsheet support webhooks?

Yes. You register a webhook against a sheet, enable it, and answer Smartsheet's verification challenge. After that it posts a short notice to your URL whenever the sheet changes, and you call the API for the details.

Do I need a developer to use the Smartsheet API?

Yes, calling the API means writing and hosting code. Smartsheet's own connectors and workflows cover a lot without it. When they don't, n-frames writes, hosts and maintains the integration for you.

How many Smartsheet API calls can I make a minute?

300 requests per minute per access token. File attachments and cell history count as 10 requests each. Over the limit, you get a 429 response and should wait before retrying.

Where is the API for Smartsheet Regions Europe?

At https://api.smartsheet.eu/2.0. Australia's at api.smartsheet.au, and Smartsheet Gov at api.smartsheetgov.com. Each region issues its own tokens.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.