Last updated

HTTP and REST

The REST URL structure follows typical resource-oriented conventions.

To get a list of sheets, use the following:

GET https://api.smartsheet.com/2.0/sheets

This returns a list of Sheet objects, where each sheet has an id attribute.

To get details on the sheet with id 123456, use the following:

GET https://api.smartsheet.com/2.0/sheets/123456

This Id pattern is repeated throughout the API. Columns, rows, cells, comments, attachments, or any other data element have a unique Id.

If you don't want to make raw HTTP calls, Smartsheet also has several Software Development Kits (SDKs) that provide a higher level interface for popular programming languages. For more information, see SDKs and Samples.

HTTP Verbs

Call the API using the following standard HTTP methods:

  • GET (to retrieve an object or list multiple objects in a specific category)
  • POST (to create)
  • PUT (to modify)
  • DELETE

HTTP Headers

Unless otherwise specified, all API endpoints expect request body data to be in JSON, and the response body data is returned as JSON.

The following HTTP request headers may be required, depending on the operation and endpoint being invoked:

HeaderDefinitionExample
AuthorizationRequired for all endpoints, except for POST /token. The access token.Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-TypeRequired for POST and PUT requests. Defines the structure for the response.application/json
smartsheet-integration-sourceSpecifies the following information about the service request:
  • Integration type
  • Smartsheet organization name
  • Client integrator name
Format: INTEGRATION-TYPE,SMAR-ORGANIZATION-NAME,INTEGRATOR-NAME

Important: All three elements, and the commas that separate them, are required.

You can set INTEGRATION-TYPE to AI, SCRIPT, APPLICATION, or PERSONAL_ACCOUNT.
AI,Sample-Organization,AI-Integrator-v2
Assume-UserOptional. As a System Admin, you can impersonate or make API calls on behalf of any user (even another System Admin) in your plan by setting Assume-User to that user's email address.

Note: In commands, such as cURL, you must URI-encode the email address.
jane.doe%40smartsheet.com

HTTP Status Codes

Smartsheet uses a combination of [](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" target="_blank" rel="noopener noreferrer">HTTP status codes and custom error codes with a descriptive message in JSON-formatted Error objects to give you a more complete picture of what has happened with your request.

HTTP
status code
MeaningTo Retry or Not to Retry?
2xxRequest was successful.

Example: 200 Success
--
4xxA problem with request prevented it from executing successfully.Never automatically retry the request.

If the error code indicates a problem that can be fixed, fix the problem and retry the request.
5xxThe request was properly formatted, but the operation failed on Smartsheet's end.In some scenarios, requests should be automatically retried using exponential backoff.

For example, doing a GET on a non-existent sheet at https://api.smartsheet.com/2.0/sheets/123456 results in an HTTP status code of 404, indicating the resource was not found.

{
"errorCode": 1006,
"message": "Not Found"
}

Some errors may contain a detail attribute set to an object with additional error details that may be useful in programmatically handling the error. If so, it is noted in the specific API operation for which the error may occur.

NOTE: Smartsheet has custom error codes to help you troubleshoot issues. See Error Codes.