# Smartsheet OpenAPI Reference Welcome to the OpenAPI reference documentation for the Smartsheet API! > **Important:** > * The Smartsheet API is restricted to users on Business and Enterprise plans > * The Developer Agreement governs the use of the Smartsheet API and Smartsheet software development kits (SDKs) **QUICKLINKS** - **Base URL:** ``` https://api.smartsheet.com/2.0/ ``` - **Getting started:** Generate an API access token and [make a request](/api/smartsheet/guides/getting-started). - **Changelog:** See the latest [API updates](/api/smartsheet/changelog). - **Schemas:** View the [object schemas](/api/smartsheet/openapi/schemas) not explicitly listed in the resource sections. - **Error codes:** Look up common API [error codes](/api/smartsheet/error-codes). - **Guides:** Learn various ways of using the API with the help of our [Guides](/api/smartsheet/introduction). Browse the Smartsheet API operations by resource on the left and start building with the Smartsheet API! Version: 2.0.0 ## Servers ``` https://api.smartsheet.com/2.0 ``` ``` https://api.smartsheet.eu/2.0 ``` ``` https://api.smartsheet.au/2.0 ``` ## Security ### OAuth2 Type: oauth2 ### APIToken API Token. Type: http Scheme: bearer ## Download OpenAPI description [Smartsheet OpenAPI Reference](https://developers.smartsheet.com/_bundle/api/smartsheet/openapi.yaml) ## Alternate Email addresses A User in Smartsheet must have a primary email address associated with their user account (User.email) and may optionally have one or more alternate email addresses associated with their account (User.alternateEmails). The following operations must be performed using an user's primary email address: * Add Group Members * Add User * Create Update Request * Share Report * Share Sheet * Share Workspace Attempting to specify a user's alternate email address for any of the above operations results in an error. ### List alternate emails - [GET /users/{userId}/alternateemails](https://developers.smartsheet.com/api/smartsheet/openapi/alternateemailaddress/list-alternate-emails.md): Gets a list of the alternate emails for the specified user. > Note: For pagination guidance, refer to Pagination. ### Add alternate emails - [POST /users/{userId}/alternateemails](https://developers.smartsheet.com/api/smartsheet/openapi/alternateemailaddress/add-alternate-email.md): Adds one or more alternate email addresses for the specified user. > Who can use this operation? > > Permissions: System Admin ### Get alternate email - [GET /users/{userId}/alternateemails/{alternateEmailId}](https://developers.smartsheet.com/api/smartsheet/openapi/alternateemailaddress/get-alternate-email.md): Gets the specified alternate email. ### Delete alternate email - [DELETE /users/{userId}/alternateemails/{alternateEmailId}](https://developers.smartsheet.com/api/smartsheet/openapi/alternateemailaddress/delete-alternate-email.md): Deletes the specified alternate email address for the specified user. ### Make alternate email primary - [POST /users/{userId}/alternateemails/{alternateEmailId}/makeprimary](https://developers.smartsheet.com/api/smartsheet/openapi/alternateemailaddress/promote-alternate-email.md): Makes the specified alternate email address to become the primary email address for the specified user. > Who can use this operation? > > Permissions: System Admin * Only Enterprise plans with this feature activated by Support can use this method. If you want to activate this feature, please contact Support. The alternate email address can only be made primary if both conditions are met: * The primary email address domain is validated * The alternate email address is confirmed or the alternate email address domain is validated ## Attachments Attachments can exist on a [comment](/api/smartsheet/openapi/comments) (that is, within a discussion), on a [row](/api/smartsheet/openapi/rows), or on a [sheet](/api/smartsheet/openapi/sheets).

Post an Attachment

Like the Smartsheet app, the Smartsheet API allows uploading files to sheets, rows, and comments. You can upload a file by performing either a simple upload or a multipart upload. A simple upload allows you to add a single file attachment to the specified object. For example, you can perform a simple upload to attach a file to a sheet, [attach a file to a row](/api/smartsheet/openapi/attachments/row-attachments-attachfile), or [attach a file to a comment](/api/smartsheet/openapi/attachments/attachments-attachtocomment). A multipart upload allows you to add a single file attachment to the specified object (that is, attach a file to a sheet, row, or comment), or to create an object and attach a file using a single request. For example, you can perform a multipart upload to [add a new comment](/api/smartsheet/openapi/comments/comments-create) that contains a single file attachment or to [add a new discussion to a sheet](/api/smartsheet/openapi/discussions/discussions-create) that contains a single file attachment. The max file size for uploads through the API is limited to 30mb. NOTE: This is a resource-intensive operation. If you encounter an error, see [Rate Limiting](/api/smartsheet/guides/advanced-topics/scalability-options).

Multipart Uploads

A multipart upload request must include the following HTTP headers: | Header | Description | | -----|-----| | **Content-Length** | The length of the request payload. | | **Content-Type** | Must be set to **multipart/form-data**, and include the boundary string that separates the parts in the request payload. | The request body of a multipart upload request contains one or more parts, each part containing either JSON or a file to upload. The request body must contain at least one part. Each part must start with the boundary string specified in the **Content-Type** request header, and must contain the following part headers: | Header | Description | | -----|-----| | **Content-Disposition** | Contains the following semicolon-delimited items:NOTE: Values specified in the Content-Disposition header must be URL-encoded. | | **Content-Type** | The content type of the part: **application/json** for JSON objects, or the applicable MIME type for file parts | The last part in the request must be followed by the boundary string, followed by two hyphens. The documentation for each operation that supports multipart uploads specifies the number and names of parts that are expected for the operation. File parts must have the part name "file", and documentation for operations which allow for JSON object parts specify the required part name for the JSON part. The following example shows a multipart upload request that creates a comment containing the specified text and file attachment: `POST https://api.smartsheet.com/2.0/sheets/4509093797881732/discussions/2889925487028100/comments` `Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789` `Content-Length: 29008` `Content-Type: multipart/form-data; boundary=----gU8h01zAAp3LagBr` `------gU8h01zAAp3LagBr` `Content-Disposition: form-data; name="comment"` `Content-Type: application/json` `{ "text": "Please review the attached image." }` `------gU8h01zAAp3LagBr` `Content-Disposition: form-data; name="file"; filename="picture.jpg"` `Content-Type: image/jpeg` *< Binary content for file >* `------gU8h01zAAp3LagBr--` NOTE: Most programming languages have libraries that can be used to assemble multipart requests.

Simple Uploads

To perform this kind of upload, you must set specific headers to tell Smartsheet about the file. The following three headers are required: Header | Description | -----|-----| **Content-Disposition** | **attachment** to tell the API that a file is in the body of the `POST` request, followed by a semicolon, followed by **filename=** and the URL-encoded filename in quotes **Content-Length** | Must be set to the size of the file, in bytes. For example to determine file size using in UNIX:

`$ ls -l ProgressReport.docx`
`5463 ProgressReport.docx`

**Content-Type** | Can be left blank if it is not known (but must be present); Smartsheet makes its best guess based on the extension of the file. The following example request shows a simple upload that adds a file attachment to a sheet: `POST https://api.smartsheet.com/2.0/sheets/4509093797881732/attachments` `Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789` `Content-Disposition: attachment; filename="ProgressReport.docx"` `Content-Type: application/msword` `Content-Length: 5463` *< Binary content for file >* As shown in this example, the contents of the file is included in the body of the `POST` request. In most programming languages, this is done by reading the file from an input stream and writing it out to the output stream of the HTTP request. ### List attachments - [GET /sheets/{sheetId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-listonsheet.md): Gets a list of all attachments that are on the sheet, including sheet, row, and discussion-level attachments. > Note: For pagination guidance, refer to Pagination. ### Attach file or URL to sheet - [POST /sheets/{sheetId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-attachtosheet.md): Attaches a file to the sheet. The URL can be any of the following: * Normal URL (attachmentType "LINK") * Box.com URL (attachmentType "BOX_COM") * Dropbox URL (attachmentType "DROPBOX") * Egnyte URL (attachmentType "EGNYTE") * Evernote URL (attachmentType "EVERNOTE") * Google Drive URL (attachmentType "GOOGLE_DRIVE") * OneDrive URL (attachmentType "ONEDRIVE") > Important: Smartsheet Gov allows only the following attachment types: > - BOX_COM > - FILE > - GOOGLE_DRIVE > - LINK > - ONEDRIVE > Important: The file size limit is 30mb. For multipart uploads please use "multipart/form-data" content type. > Note: Posting a file attachment is resource-intensive and is limited to 30 requests per minute per API token. For details, see Rate limiting. ### Get attachment - [GET /sheets/{sheetId}/attachments/{attachmentId}](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-get.md): Fetches a temporary URL that allows you to download an attachment. The urlExpiresInMillis attribute tells you how long the URL is valid. ### Delete attachment - [DELETE /sheets/{sheetId}/attachments/{attachmentId}](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-delete.md): Deletes the attachment specified in the URL. ### List versions - [GET /sheets/{sheetId}/attachments/{attachmentId}/versions](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-versionlist.md): Gets a list of all versions of the given attachmentId in order from newest to oldest. > Note: For pagination guidance, refer to Pagination. ### Attach new version - [POST /sheets/{sheetId}/attachments/{attachmentId}/versions](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-versionupload.md): Uploads a new version of a file to a sheet or row. This operation can be performed using a simple upload or a multipart upload. > Important: The file size limit is 30mb. ### Delete all versions - [DELETE /sheets/{sheetId}/attachments/{attachmentId}/versions](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-versionsdelete.md): Deletes all versions of the attachment corresponding to the specified attachmentId. For attachments with multiple versions, this effectively deletes the attachment from the object that it’s attached to. ### Attach file or URL to comment - [POST /sheets/{sheetId}/comments/{commentId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-attachtocomment.md): Attaches a file to the comment. The URL can be any of the following: * Normal URL (attachmentType "LINK") * Box.com URL (attachmentType "BOX_COM") * Dropbox URL (attachmentType "DROPBOX") * Egnyte URL (attachmentType "EGNYTE") * Evernote URL (attachmentType "EVERNOTE") * Google Drive URL (attachmentType "GOOGLE_DRIVE") * OneDrive URL (attachmentType "ONEDRIVE") > Important: Smartsheet Gov allows only the following attachment types: > - BOX_COM > - FILE > - GOOGLE_DRIVE > - LINK > - ONEDRIVE > Important: The file size limit is 30mb. This operation can be performed using a simple upload or a multipart upload. > Note: Posting a file attachment is resource-intensive and is limited to 30 requests per minute per API token. For details, see Rate limiting. ### List discussion attachments - [GET /sheets/{sheetId}/discussions/{discussionId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/discussion-listattachments.md): Gets a list of all attachments that are in the discussion. > Note: For pagination guidance, refer to Pagination. ### List row attachments - [GET /sheets/{sheetId}/rows/{rowId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/attachments-listonrow.md): Gets a list of all attachments that are on the row, including row and discussion-level attachments. > Note: For pagination guidance, refer to Pagination. ### Attach file or URL to row - [POST /sheets/{sheetId}/rows/{rowId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/row-attachments-attachfile.md): Attaches a file to the row. The URL can be any of the following: * Normal URL (attachmentType "LINK") * Box.com URL (attachmentType "BOX_COM") * Dropbox URL (attachmentType "DROPBOX") * Egnyte URL (attachmentType "EGNYTE") * Evernote URL (attachmentType "EVERNOTE") * Google Drive URL (attachmentType "GOOGLE_DRIVE") * OneDrive URL (attachmentType "ONEDRIVE") > Important: Smartsheet Gov allows only the following attachment types: > - BOX_COM > - FILE > - GOOGLE_DRIVE > - LINK > - ONEDRIVE > Important: The file size limit is 30mb. For multipart uploads please use "multipart/form-data" content type. > Note: Posting a file attachment is resource-intensive and is limited to 30 requests per minute per API token. For details, see Rate limiting. ### List discussion attachments - [GET /sheets/{sheetId}/discussions/{discussionId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/discussions/discussion-listattachments.md): Gets a list of all attachments that are in the discussion. > Note: For pagination guidance, refer to Pagination. ## Discussions A discussion is a container for a collection of individual [comments](/api/smartsheet/openapi/comments) within a single thread. A discussion can exist on a [row](/api/smartsheet/openapi/rows) or a [sheet](/api/smartsheet/openapi/sheets). In the UI, Smartsheet creates a discussion to contain each top-level comment and subsequent replies into a single thread. Using the API, you can only add a comment to a discussion. If the discussion doesn't already exist, you must create it first. A discussion is a collection of one or more comments, each of which may contain attachments.

Discussion Attachments

For details about working with the attachments within a discussion, see [Attachments](/api/smartsheet/openapi/attachments).

Discussion Comments

For details about working with a discussion's comments, see [Comments](/api/smartsheet/openapi/comments). ### List discussion attachments - [GET /sheets/{sheetId}/discussions/{discussionId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/attachments/discussion-listattachments.md): Gets a list of all attachments that are in the discussion. > Note: For pagination guidance, refer to Pagination. ### List discussions - [GET /sheets/{sheetId}/discussions](https://developers.smartsheet.com/api/smartsheet/openapi/discussions/discussions-list.md): Gets a list of all discussions associated with the specified sheet. Remember that discussions are containers for the conversation thread. To see the entire thread, use the include=comments parameter. > Note: For pagination guidance, refer to Pagination. ### Create discussion - [POST /sheets/{sheetId}/discussions](https://developers.smartsheet.com/api/smartsheet/openapi/discussions/discussions-create.md): Creates a new discussion on a sheet. To create a discussion with an attachment please use "multipart/form-data" content type. ### Get discussion - [GET /sheets/{sheetId}/discussions/{discussionId}](https://developers.smartsheet.com/api/smartsheet/openapi/discussions/discussion-get.md): Gets the discussion specified by discussionId. ### Delete a discussion - [DELETE /sheets/{sheetId}/discussions/{discussionId}](https://developers.smartsheet.com/api/smartsheet/openapi/discussions/discussion-delete.md): Deletes the discussion specified in the URL. ### List discussion attachments - [GET /sheets/{sheetId}/discussions/{discussionId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/discussions/discussion-listattachments.md): Gets a list of all attachments that are in the discussion. > Note: For pagination guidance, refer to Pagination. ### List discussions with a row - [GET /sheets/{sheetId}/rows/{rowId}/discussions](https://developers.smartsheet.com/api/smartsheet/openapi/discussions/row-discussions-list.md): Gets a list of all discussions associated with the specified row. Remember that discussions are containers for the conversation thread. To see the entire thread, use the include=comments parameter. > Note: For pagination guidance, refer to Pagination. ### Create a discussion on a row - [POST /sheets/{sheetId}/rows/{rowId}/discussions](https://developers.smartsheet.com/api/smartsheet/openapi/discussions/row-discussions-create.md): Creates a new discussion on a row. To create a discussion with an attachment please use "multipart/form-data" content type. ## Automation Rules Automation is a catch-all term for approvals, notifications, and update requests. You can delete, update, or retrieve various automation settings through the API. You cannot create new automation rules programmatically.

Disabled Reasons for Automation Rules

Reason | Description | -----|-----| **APPROVAL_COLUMN_MISSING** | This rule's approval status column has been deleted. **APPROVAL_COLUMN_WRONG_TYPE** | The approval column must be a dropdown column. **AUTOMATION_NOT_ENABLED_FOR_ORG** | To create or edit automated actions, you need to upgrade your organization account to a Business or Enterprise plan. **COLUMN_MISSING** | A column referenced by this rule has been deleted. **COLUMN_TYPE_INCOMPATIBLE** | A column referenced by this rule has been changed to an incompatible column type. **NO_POTENTIAL_RECIPIENTS** | This rule has no recipients that will be able to receive notifications based on this sheet's permission settings or this account's approved domain sharing list. **NO_VALID_SELECTED_COLUMNS** | All selected columns for this rule have been deleted. ### List all automation rules - [GET /sheets/{sheetId}/automationrules](https://developers.smartsheet.com/api/smartsheet/openapi/automationrules/automationrules-list.md): Returns all automation rules associated with the specified sheet. Multistep workflows are not returned via the API. Instead, you'll see an error 400 - 1266: This rule is not accessible through the API. Only single-action notifications, approval requests, or update requests qualify. For users of Smartsheet for Slack, note that Slack notifications are not returned. > Note: For pagination guidance, refer to Pagination. ### Get an automation rule - [GET /sheets/{sheetId}/automationrules/{automationRuleId}](https://developers.smartsheet.com/api/smartsheet/openapi/automationrules/automationrule-get.md): Returns the specified automation rule, including any action values. ### Update an automation rule - [PUT /sheets/{sheetId}/automationrules/{automationRuleId}](https://developers.smartsheet.com/api/smartsheet/openapi/automationrules/automationrule-update.md): Updates an existing automation rule. When sending an AutomationRule, you must always specify action.type and it must match the existing rule type. ### Delete an automation rule - [DELETE /sheets/{sheetId}/automationrules/{automationRuleId}](https://developers.smartsheet.com/api/smartsheet/openapi/automationrules/automationrule-delete.md): Deletes an automation rule. ## Cell Images A cell image is an image that has been uploaded to a cell within a sheet. ### List image URLs - [POST /imageurls](https://developers.smartsheet.com/api/smartsheet/openapi/cellimages/listimageurls.md): Posts an array of Image Url objects that can be used to retrieve the specified cell images. ### Add image to cell - [POST /sheets/{sheetId}/rows/{rowId}/columns/{columnId}/cellimages](https://developers.smartsheet.com/api/smartsheet/openapi/cellimages/addimagetocell.md): Uploads an image to the specified cell within a sheet. ## Cells A collection of cells comprises each row in a sheet.

Cell Links

Creating or updating cell links via the **cell.linkInFromCell** attribute is a special operation. A given row or cell update operation may contain only link updates, or no link updates. Attempting to mix row/cell updates with cell link updates results in error code 1115. Additionally, a [CellLink object](/api/smartsheet/openapi/schemas/celllink) can only be added to an existing cell, so the **cell.linkInFromCell** attribute is not allowed when POSTing a new row to a sheet. When creating a cell link, **cell.value** must be null (the data is pulled from the linked cell). A cell may not contain both a hyperlink and a cell link, so **hyperlink** and **linkInFromCell** may never both be non-null at the same time.

Cell Reference

Cell Value Representation

[Cell objects](/api/smartsheet/openapi/cells/cell) retrieved through the Smartsheet APIs have two main attributes representing cell values: **Cell.value**, and **Cell.displayValue**. A third attribute, **Cell.objectValue** is currently used only for adding and updating predecessors, or for multi-contact or multi-picklist details, such as email addresses or values in a multi-picklist. An empty cell returns no value. **Cell.displayValue** is always a string and is only returned for certain column types (see below). It represents the formatted value as it should be displayed to an end-user. For example, if a TEXT_NUMBER column is formatted as a US Dollar currency, its **value** may be a number like 1234.5678, but its **displayValue** is "$1,234.57". **Cell.value** represents a cell's raw value and can be one of the following primitive JSON types: string, number, or Boolean, depending on the column type. An empty cell returns no value. Complex types are represented as strings, formatted as described below: Help with Project Columns Column Type | Possible Types for Cell.value | Returns Cell.displayValue? ------------|-------------------------------|--------------------------- ABSTRACT_DATETIME | string: a project date and time in ISO-8601 format, or a free-form text value.
number: see [Dates and Times](/api/smartsheet/guides/basics/dates-and-times) for how to request dates to be returned as numbers. | No. CHECKBOX | Boolean: **true** if the checkbox is checked, **false** if unchecked, no value if the cell hasn't been touched yet.
string: a free-form text value. | No. CONTACT_LIST | string: an email address representing a contact, or a free-form text value. | Yes: same as **value** for free-form strings; for contacts, the contact's name if any, else their email address. DATE | string: a date in ISO-8601 format, or a free-form text value.
number: see [Dates and Times](/api/smartsheet/guides/basics/dates-and-times) for how to request dates to be returned as numbers. | No. DURATION | string: a duration value such as "4d 6h 30m" in the user's locale, or a free-form text value.
See the Help Center for more information on durations. | Yes: same as **value** MULTI_CONTACT_LIST | string: only visible when using a query parameter of **level** and the value appropriate to the dashboard, report, or sheet that you are querying, otherwise the column type is TEXT_NUMBER. | Yes: same as **value**; to see actual email addresses, see below. MULTI_PICKLIST | string: only visible when using a query parameter of **level** and the value appropriate to the dashboard, report, or sheet that you are querying, otherwise the column type is TEXT_NUMBER. | Yes: same as **value**; to see objectValue, see below. PICKLIST | string: one of the picklist's column options, or a free-form text value.
number: numeric values | Yes: same as **value** for strings; for number values, the number with formatting applied. PREDECESSOR | string: a comma-delimited predecessor list such as "12FS +3d 4h, 14SS", or a free-form text value.
See the Help Center for more information on predecessors. | Yes: same as **value** TEXT_NUMBER | string: free-form text values
number: numeric values | Yes: same as **value** for strings; for number values, the number with formatting applied. **Cell.objectValue** is an object representation of a cell's value and is currently used for adding or updating predecessor cell values, or for multi-contact details, such as email addresses. * For predecessors, it provides a more "programmer friendly" format for assembling predecessors. To update a cell's predecessors, set **objectValue** to a [PredecessorList object](/api/smartsheet/openapi/schemas/predecessorlist) containing [Predecessor objects](/api/smartsheet/openapi/schemas/predecessor). * For multi-contact or multi-picklist details, use both a level query parameter *and* an **include=objectValue** query to see email addresses rather than display names or to see multi-picklist values.

Cell Value Parsing

The flexibility in cell value data types is a powerful feature in the Smartsheet application; however, it poses a challenge for an API in terms of parsing. Being too flexible might result in unexpected behavior. For instance, if you write code to post a Date value to a Smartsheet and the API operation succeeds, you might assume that the date value you sent was interpreted as date. What happens if you posted your date in the wrong format? Do you really want Smartsheet to keep the malformed date as a string value? Probably not. To address this problem, the Smartsheet API employs a simple scheme to indicate whether you want a more predictable and strict interface or a more flexible one. By default, a cell value is expected to conform to "strict" rules for the type of the cell's column. If an input value doesn't conform, the API returns [error code 1042](/api/smartsheet/error-codes). If, however, you want the same flexibility as the Smartsheet Web app, you can disable the strict rules, and we'll do our best to make sense of it. To enable lenient parsing simply include **"strict": false** in the [Cell object](/api/smartsheet/openapi/cells/cell) in your request body. NOTE: How does strict cell value parsing compare to cell validation settings? Strict cell value parsing determines how string values are parsed. It is set on a per-call basis. In contrast, cell validation is part of the column definition. The overrideValidation property is restricted to sheet admins and does not override strict parsing. The parsing rules for the various column types are as follows: **ABSTRACT_DATETIME** Value | Description | -----|-----| **lenient** | Smartsheet attempts to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, Smartsheet recognizes the date and stores it as such. All other values are simply text values. **strict** | The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of **numericDates** set to **true** to have Smartsheet convert epoch time to human readable dates. See [Dates and Times](/api/smartsheet/guides/basics/dates-and-times) for more information. **CHECKBOX** Value | Description | -----|-----| **lenient** | Boolean values and string values of **true** and **false** are handled the same as **strict**. All other values are saved as text values. **strict** | Only Boolean values (true or false) are valid. **CONTACT_LIST** Value | Description | -----|-----| **lenient** | If the value is a valid email address, Smartsheet handles it the same as **strict**. If not, Smartsheet saves the value as a text value. **strict** | The value must be a valid email address. If **displayValue** is set, Smartsheet uses that as the name; otherwise, if Smartsheet finds a match among the the access token owner's contacts, Smartsheet associates this cell with that existing contact. NOTE: See the [Contact List Columns](/api/smartsheet/openapi/cells) section for more information. **DATE** Value | Description | -----|-----| **lenient** | Smartsheet attempts to convert the string value to date using ISO 8601 date format, as well as several locale-specific date formats. If the value is a parsable date format, Smartsheet recognizes the date and stores it as such. All other values are simply text values. **strict** | The value must be a string value and a valid ISO 8601 date (YYYY-MM-DD). Alternatively, if Unix time (also known as epoch time) is used, you can use the query parameter of **numericDates** set to **true** to have Smartsheet convert epoch time to human readable dates. See [Dates and Times](/api/smartsheet/guides/basics/dates-and-times) for more information. **DURATION** Value | Description | -----|-----| **lenient** | Numeric values are treated as duration values in days. String values which are valid duration strings in the user's locale are treated as durations, and any other values are treated as free-form text values. **strict** | Only valid duration strings in the user's locale are valid. Information on duration strings can be found in the Help Center. NOTE: You may use the query string parameter projectParseLocale with a [supported locale string](/api/smartsheet/openapi/serverinfo) to force parsing in the specified locale (for example, using en_US lets you send in English values regardless of the user's locale). **MULTI_CONTACT_LIST** Value | Description | -----|-----| N/A | Set using the **objectValue** attribute for the Cell object, which is inherently strict. See [Cell Reference](/api/smartsheet/openapi/cells). **MULTI_PICKLIST** Value | Description | -----|-----| N/A | Set using the **objectValue** attribute for the Cell object, which is inherently strict. See [Cell Reference](/api/smartsheet/openapi/cells). **PICKLIST** Value | Description | -----|-----| **lenient** | All numeric and text values are valid. Formatted numbers are parsed like TEXT_NUMBER formatted numbers. **strict** | The value must be a string and must be one of the options for the picklist. **PREDECESSOR** Value | Description | -----|-----| N/A | Set using the **objectValue** attribute for the Cell object, which is inherently strict. See [Cell Reference](/api/smartsheet/openapi/cells). **TEXT_NUMBER** Value | Description | -----|-----| **lenient** | All numeric and text values are valid. Formatted numbers passed as text values, such as currencies ("$5,000"), percentages ("50%"), or decimals ("100.5") are parsed to their numeric equivalents, based on the locale of the access token owner, with the proper formatting enabled for the cell. **strict** | All numeric and text values are valid and are interpreted literally. NOTE: The Smartsheet application only supports numeric values in the range -9007199254740992 to 9007199254740992. If using strict parsing, any numeric value outside that range results in [error code 1148](/api/smartsheet/error-codes). If using lenient parsing, the value is silently converted to text.

Contact List Columns

With columns of type **CONTACT_LIST**, the cell attributes **value** and **displayValue** are treated independently. The contact's email address is represented by **value**, while the contact's name (and the value displayed in the cell in the Smartsheet app) is represented by **displayValue**. When creating or updating cells for a contact list column, the **displayValue** attribute works as follows: * If **displayValue** is non-null and non-empty, the Smartsheet cell displays the value provided. * If **displayValue** is an empty string, the Smartsheet cell displays the email address. * If **displayValue** is null or absent, Smartsheet makes a best guess effort at filling it in with a contact's name based on the email address.

Hyperlinks

You can create and modify [hyperlinks](/api/smartsheet/openapi/schemas/hyperlink) by using any API operation that creates or updates cell data. When creating or updating a hyperlink, **cell.value** may be set to a string value or null. If null, the cell's value is derived from the hyperlink: * If the hyperlink is a URL link, the cell's value is set to the URL itself. * If the hyperlink is a dashboard, report, or sheet link, the cell's value is set to the dashboard, report, or sheet name.

Images in Cells

For details about working with images in cells, see [Cell Images](/api/smartsheet/openapi/cellimages). ### List cell history - [GET /sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history](https://developers.smartsheet.com/api/smartsheet/openapi/cells/cellhistory-get.md): Gets the cell modification history. > Note: Fetching cell history is resource-intensive and is limited to 30 requests per minute per API token. For details, see Rate limiting. > Note: For pagination guidance, refer to Pagination. ## Columns A column is a component of a sheet or report.

Column Types

Smartsheet supports the following standard column types, which are represented in a [Column object](/api/smartsheet/openapi/columns/column) with a **type** attribute set to one of the following: Column Type | Column.type Value | Notes | ---|---|---| Checkbox | **CHECKBOX** | Checkbox, star, and flag types | Contact List | **CONTACT_LIST** | List containing contacts or roles for a project. **Note:** You can use the [contactOptions](/api/smartsheet/openapi/schemas/contactoption) property to specify a pre-defined list of values for the column, which can also become lanes in card view. | Contact List | **MULTI_CONTACT_LIST** | List where single cells can contain more than one contact. Only visible when using a query parameter of **level** and the value appropriate to the dashboard, report, or sheet that you are querying. To see email addresses behind the display names, combine an **include=objectValue** query parameter with a **level** query parameter. | Date | **DATE** | | Date/Time | **ABSTRACT_DATETIME** | Represents a project sheet's start and end dates.
**Only for dependency-enabled project sheets**
The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) Additionally, the API does not support updating data in the "End Date" column under any circumstance, and does not support updating data in the "Start Date" column if "Predecessor" is set for that row. | Date/Time | **DATETIME** | Used only by the following system-generated columns: | Dropdown List | **PICKLIST** | Custom, RYG, Harvey ball, priority types, etc. | Dropdown List | **MULTI_PICKLIST** | List where single cells can contain more than one dropdown item. Only visible when using a query parameter of **level** and the value appropriate to the dashboard, report, or sheet that you are querying. To see multi-picklist values behind the display names, combine an **include=objectValue** query parameter with a **level** query parameter. | Duration | **DURATION** | **Only for dependency-enabled project sheets**
The API does not support setting a column to this type. (This can only be done through the Smartsheet Web app when configuring a project sheet.) | Predecessor | **PREDECESSOR** | Defines what must happen first in a project flow. For more information, see the [Predecessor object](/api/smartsheet/openapi/schemas/predecessorlist). **Only for dependency-enabled project sheets** | Text/Number | **TEXT_NUMBER** | | NOTE: See the [Cell Reference](/api/smartsheet/openapi/cells) section for information on getting and setting cell values for the different column types.

Symbol Columns

In addition to the basic column types above, the Smartsheet app also supports columns that display symbols. These are specialized columns of type **CHECKBOX** or **PICKLIST**, whose **symbol** attribute is set to one of the values below: **Symbols for CHECKBOX columns:** ![A flag symbol](./images/img_pl_flagc.png) Value | Example | -----|-----| **FLAG** | A flag symbol | **STAR** | A star symbol | **Symbols for PICKLIST columns:** Value | Example | -----|-----| **ARROWS_3_WAY** | An arrows_3_way symbol | **ARROWS_4_WAY** | An arrows_4_way symbol | **ARROWS_5_WAY** | An arrows_5_way symbol | **DECISION_SHAPES** | A decision_shapes symbol | **DECISION_SYMBOLS** | A decision_symbols symbol | **DIRECTIONS_3_WAY** | A directions_3_way symbol | **DIRECTIONS_4_WAY** | A directions_4_way symbol | **EFFORT** | An effort symbol | **HARVEY_BALLS** | A harvey_balls symbol | **HEARTS** | A hearts symbol | **MONEY** | A money symbol | **PAIN** | A pain symbol | **PRIORITY** | A priority symbol | **PRIORITY_HML** | A priority_hml symbol | **PROGRESS** | A progress symbol | **RYG** | An RYG symbol | **RYGB** | An RYGB symbol | **RYGG** | An RYGG symbol | **SIGNAL** | A signal symbol | **SKI** | A ski symbol | **STAR_RATING** | A star_rating symbol **VCR** | A VCR symbol | **WEATHER** | A weather symbol | NOTE: The Smartsheet grid user interface presents several row attributes and features visually as columns, for example, attachments, discussions, row action indicator, or row number. The API does not consider these to be columns, and does not return or otherwise expose them as columns. The only columns returned by the API are user data columns.

System Columns

In addition to the standard column types and symbols, Smartsheet has a number of system columns, which represent data that is filled in by Smartsheet and whose values cannot be changed by the user. These columns are represented with standard [column types](/api/smartsheet/openapi/columns), with the [**Column.systemColumnType**](/api/smartsheet/openapi/columns/column) attribute set to one of the following: Column.systemColumnType Value | Column Type | Notes -----|-----|-----| **AUTO_NUMBER** | TEXT_NUMBER | Columns of this system column type include an [AutoNumberFormat object](/api/smartsheet/openapi/schemas/autonumberformat) that describes the mask used to generate the value. **CREATED_BY** | CONTACT_LIST **CREATED_DATE** | DATETIME **MODIFIED_BY** | CONTACT_LIST **MODIFIED_DATE** | DATETIME ### List columns - [GET /sheets/{sheetId}/columns](https://developers.smartsheet.com/api/smartsheet/openapi/columns/columns-listonsheet.md): Gets a list of all columns belonging to the sheet specified in the URL. > Note: For pagination guidance, refer to Pagination. ### Add columns - [POST /sheets/{sheetId}/columns](https://developers.smartsheet.com/api/smartsheet/openapi/columns/columns-addtosheet.md): Inserts one or more columns into the sheet specified in the URL.This operation can be performed using a simple upload or a multipart upload. For more information, see Post an Attachment. ### Get column - [GET /sheets/{sheetId}/columns/{columnId}](https://developers.smartsheet.com/api/smartsheet/openapi/columns/column-get.md): Gets definitions for the column specified in the URL. Note: If you need to see the values of individual cells within the column, use Get Sheet or Get Row. ### Delete column - [DELETE /sheets/{sheetId}/columns/{columnId}](https://developers.smartsheet.com/api/smartsheet/openapi/columns/column-delete.md): Deletes the column specified in the URL. ### Update column - [PUT /sheets/{sheetId}/columns/{columnId}](https://developers.smartsheet.com/api/smartsheet/openapi/columns/column-updatecolumn.md): Updates properties of the column, moves the column, or renames the column. Note: * You cannot change the type of a Primary column. * While dependencies are enabled on a sheet, you can't change the type of any special calendar/Gantt columns. * If the column type is changed, all cells in the column are converted to the new column type and column validation is cleared. * Type is optional when moving or renaming, but required when changing type or dropdown values. ## Comments A discussion is a container for a number of individual comments in a threaded conversation. For more details, see the [Discussion](/api/smartsheet/openapi/discussions) section. This section describes operations on an *individual* comment within a discussion thread. * To retrieve all discussions and comments for an entire sheet, use [List Discussions](/api/smartsheet/openapi/discussions/discussions-list) with the query parameter **include=comments**. * To retrieve all discussions and comments associated with a row, use [List Row Discussions](/api/smartsheet/openapi/discussions/row-discussions-list) with the query parameter **include=comments**. A comment can contain one or more attachments.

Comment Attachments

For details about working with a comment's attachments, see [Attachments](/api/smartsheet/openapi/attachments). ### Get a comment - [GET /sheets/{sheetId}/comments/{commentId}](https://developers.smartsheet.com/api/smartsheet/openapi/comments/comment-get.md): Gets the comment specified by commentId. ### Edit a comment - [PUT /sheets/{sheetId}/comments/{commentId}](https://developers.smartsheet.com/api/smartsheet/openapi/comments/comment-edit.md): Updates the text of a comment. NOTE: Only the user that created the comment is permitted to update it. ### Delete a comment - [DELETE /sheets/{sheetId}/comments/{commentId}](https://developers.smartsheet.com/api/smartsheet/openapi/comments/comment-delete.md): Deletes the comment specified in the URL. ### Create a comment - [POST /sheets/{sheetId}/discussions/{discussionId}/comments](https://developers.smartsheet.com/api/smartsheet/openapi/comments/comments-create.md): Adds a comment to a discussion. To create a comment with an attachment please use "multipart/form-data" content type. ## Contacts A contact is a user's personal contact in Smartsheet (as described in the Help Center article, Managing Contacts. ### List contacts - [GET /contacts](https://developers.smartsheet.com/api/smartsheet/openapi/contacts/list-contacts.md): Gets a list of the user's Smartsheet contacts. > Note: For pagination guidance, refer to Pagination. ### Get contact - [GET /contacts/{contactId}](https://developers.smartsheet.com/api/smartsheet/openapi/contacts/get-contact.md): Gets the specified contact. ## Cross-sheet References To create a formula that references data in another sheet, you must first create a cross-sheet reference between the detail sheet and the source sheet. That reference must also define the cell range. Once you have created the cross-sheet reference, you can use the reference name in any formula on the detail sheet. To create the formula, use Add Rows or Update Rows. Cross-sheet references that are not used by any formula are automatically deleted after two hours. ### Create cross-sheet references - [POST /sheets/{sheetId}/crosssheetreferences](https://developers.smartsheet.com/api/smartsheet/openapi/crosssheetreferences/add-crosssheet-reference.md): Adds a cross-sheet reference between two sheets and defines the data range for formulas. Each distinct data range requires a new cross-sheet reference. ### List cross-sheet references - [GET /sheets/{sheetId}/crosssheetreferences](https://developers.smartsheet.com/api/smartsheet/openapi/crosssheetreferences/list-crosssheet-references.md): Lists all cross-sheet references for the sheet. > Note: For pagination guidance, refer to Pagination. ### Get cross-sheet reference - [GET /sheets/{sheetId}/crosssheetreferences/{crossSheetReferenceId}](https://developers.smartsheet.com/api/smartsheet/openapi/crosssheetreferences/get-crosssheet-reference.md): Gets the cross-sheet reference specified in the URL. ## Dashboards Smartsheet dashboards are a collection of widgets that can contain data from a variety of different data sources (for example, sheets, reports, or custom data). Dashboards were once called Sights(TM) and this name is still present in object names, endpoint paths, and other places. ### List dashboards - [GET /sights](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/list-sights.md): Gets a list of all dashboards that the user has access to. > Note: For pagination guidance, refer to Token-based pagination. ### Get Dashboard - [GET /sights/{sightId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/get-sight.md): Gets the specified dashboard. ### Update dashboard - [PUT /sights/{sightId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/update-sight.md): Updates (renames) the specified dashboard. ### Delete dashboard - [DELETE /sights/{sightId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/delete-sight.md): Deletes the dashboard specified in the URL. ### Copy dashboard - [POST /sights/{sightId}/copy](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/copy-sight.md): Creates a copy of the specified dashboard. ### Move dashboard - [POST /sights/{sightId}/move](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/move-sight.md): Moves the specified dashboard to a new location. ### Get dashboard publish status - [GET /sights/{sightId}/publish](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/get-sight-publish-status.md): Gets the dashboard 'publish' settings. ### Set dashboard publish status - [PUT /sights/{sightId}/publish](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/set-sight-publish-status.md): Publishes or unpublishes a dashboard. ### Share dashboard (deprecated) - [POST /sights/{sightId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/share-sight.md): Shares a dashboard with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List dashboard shares (deprecated) - [GET /sights/{sightId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/list-sight-shares.md): Gets a list of all users and groups to whom the specified dashboard is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get dashboard share (deprecated) - [GET /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/share-sight-get.md): Gets a list of all users and groups to whom the specified dashboard is shared, and their access level. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete dashboard share (deprecated) - [DELETE /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/delete-sight-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update dashboard share (deprecated) - [PUT /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/update-sight-share.md): Updates the access level of a user or group for the specified dashboard. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Share dashboard (deprecated) - [POST /sights/{sightId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-sight.md): Shares a dashboard with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List dashboard shares (deprecated) - [GET /sights/{sightId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-sight-shares.md): Gets a list of all users and groups to whom the specified dashboard is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get dashboard share (deprecated) - [GET /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-sight-get.md): Gets a list of all users and groups to whom the specified dashboard is shared, and their access level. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete dashboard share (deprecated) - [DELETE /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-sight-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update dashboard share (deprecated) - [PUT /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-sight-share.md): Updates the access level of a user or group for the specified dashboard. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ## Sharing Use the *Sharing* operations to control sharing of dashboards, reports, sheets, and workspaces. ### Share dashboard (deprecated) - [POST /sights/{sightId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/share-sight.md): Shares a dashboard with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List dashboard shares (deprecated) - [GET /sights/{sightId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/list-sight-shares.md): Gets a list of all users and groups to whom the specified dashboard is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get dashboard share (deprecated) - [GET /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/share-sight-get.md): Gets a list of all users and groups to whom the specified dashboard is shared, and their access level. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete dashboard share (deprecated) - [DELETE /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/delete-sight-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update dashboard share (deprecated) - [PUT /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/dashboards/update-sight-share.md): Updates the access level of a user or group for the specified dashboard. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Share report (deprecated) - [POST /reports/{reportId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/reports/share-report.md): Shares a Report with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List report shares (deprecated) - [GET /reports/{reportId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/reports/list-report-shares.md): Gets a list of all users and groups to whom the specified Report is shared, and their access level. This operation supports query string parameters for pagination of results. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get report share (deprecated) - [GET /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/reports/share-report-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete report share (deprecated) - [DELETE /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/reports/delete-report-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update report share (deprecated) - [PUT /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/reports/update-report-share.md): Updates the access level of a user or group for the specified report. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List asset shares - [GET /shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-asset-shares.md): Retrieves a list of all users and groups to whom the specified asset is shared, and their access level. This operation supports query string parameters for pagination of results. > Note: For pagination guidance, refer to Token-based pagination. ### Share asset - [POST /shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-asset.md): Shares an asset with the specified users and/or groups. One (and only one) of the following is required (alongside accessLevel): - email - groupId ### Get asset share - [GET /shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/get-asset-share.md): Retrieves a specific share for the specified asset. ### Update asset share - [PATCH /shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-asset-share.md): Updates the share for a specified asset. > Note: This operation doesn't support asset ownership transfer. ### Delete asset share - [DELETE /shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-asset-share.md): Deletes the share for a specified asset. ### Share report (deprecated) - [POST /reports/{reportId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-report.md): Shares a Report with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List report shares (deprecated) - [GET /reports/{reportId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-report-shares.md): Gets a list of all users and groups to whom the specified Report is shared, and their access level. This operation supports query string parameters for pagination of results. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get report share (deprecated) - [GET /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-report-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete report share (deprecated) - [DELETE /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-report-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update report share (deprecated) - [PUT /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-report-share.md): Updates the access level of a user or group for the specified report. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Share sheet (deprecated) - [POST /sheets/{sheetId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-sheet.md): Shares a sheet with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List sheet shares (deprecated) - [GET /sheets/{sheetId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-sheet-shares.md): Gets a list of all users and groups to whom the specified Sheet is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get sheet share (deprecated) - [GET /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-sheet-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete sheet share (deprecated) - [DELETE /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-sheet-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update sheet share (deprecated) - [PUT /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-sheet-share.md): Updates the access level of a user or group for the specified sheet. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Share dashboard (deprecated) - [POST /sights/{sightId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-sight.md): Shares a dashboard with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List dashboard shares (deprecated) - [GET /sights/{sightId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-sight-shares.md): Gets a list of all users and groups to whom the specified dashboard is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get dashboard share (deprecated) - [GET /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-sight-get.md): Gets a list of all users and groups to whom the specified dashboard is shared, and their access level. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete dashboard share (deprecated) - [DELETE /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-sight-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update dashboard share (deprecated) - [PUT /sights/{sightId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-sight-share.md): Updates the access level of a user or group for the specified dashboard. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Share workspace (deprecated) - [POST /workspaces/{workspaceId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-workspace.md): Shares a Workspace with the specified users and groups. This operation supports both single-object and bulk semantics. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List workspace shares (deprecated) - [GET /workspaces/{workspaceId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-workspace-shares.md): Gets a list of all users and groups to whom the specified Workspace is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get workspace share (deprecated) - [GET /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-workspace-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete workspace share (deprecated) - [DELETE /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-workspace-share.md): Deletes the share specified in the URL. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update workspace share (deprecated) - [PUT /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-workspace-share.md): Updates the access level of a user or group for the specified workspace. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Share sheet (deprecated) - [POST /sheets/{sheetId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/share-sheet.md): Shares a sheet with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List sheet shares (deprecated) - [GET /sheets/{sheetId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/list-sheet-shares.md): Gets a list of all users and groups to whom the specified Sheet is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get sheet share (deprecated) - [GET /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/share-sheet-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete sheet share (deprecated) - [DELETE /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/delete-sheet-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update sheet share (deprecated) - [PUT /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/update-sheet-share.md): Updates the access level of a user or group for the specified sheet. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Share workspace (deprecated) - [POST /workspaces/{workspaceId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/share-workspace.md): Shares a Workspace with the specified users and groups. This operation supports both single-object and bulk semantics. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List workspace shares (deprecated) - [GET /workspaces/{workspaceId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/list-workspace-shares.md): Gets a list of all users and groups to whom the specified Workspace is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get workspace share (deprecated) - [GET /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/share-workspace-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete workspace share (deprecated) - [DELETE /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/delete-workspace-share.md): Deletes the share specified in the URL. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update workspace share (deprecated) - [PUT /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/update-workspace-share.md): Updates the access level of a user or group for the specified workspace. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ## Events Smartsheet uses event objects to capture actions such as creating, updating, loading, deleting, and more for items such as sheets, reports, dashboards, attachments, and users. With **Event Reporting**, you can use the operations described here to programmatically retrieve these events. > **Note:** Event Reporting is a premium add-on available for Enterprise and Advanced Work Management plans only. For details on the add-on, please contact our Sales Team.

Event types

All events derive from the [Event](/api/smartsheet/openapi/events/event) schema. Each event type overrides Event's `objectType` and `action` properties with its specific object type and a typical action performed on that object. Furthermore, each event type's `additionalDetails` object has properties specific to the event type. See [Event types](/api/smartsheet/event-types.md) for the complete event listing, details, and example objects.

System users

System components perform some actions in Smartsheet. Therefore, the `userId` property in some response payloads refers to a system user--not to a regular user. For example, the Smartsheet Events API shows 5629504736520068 as the `userId` when an anonymous user accesses a sheet that is published for anyone. The system users are listed below. New system `userIds` may be incorporated to this list as new features and subsystems are incorporated to Smartsheet: System user | Description | -----|-----| 1688855062570884 | Data accessed/modified by Skype action (only possible if Smartsheet account is connected to Skype) | 2814754969413508 | Data accessed/modified by Trello import action (only possible if Smartsheet account is connected to Trello) | 3377704922834820 | Data accessed/modified due to Smartsheet cell-link | 3940654876256132 | Data accessed/modified by the Smartsheet Automation system | 5066554783098756 | Access to object published to any user in the Smartsheet organization account | 5629504736520068 | Access to Smartsheet object published to anyone | 6192454689941380 | Data accessed/modified by the Smartsheet Notification system | 7881304550205316 | Data accessed/modified by Smartsheet Form submission | ### List events - [GET /events](https://developers.smartsheet.com/api/smartsheet/openapi/events/list-events.md): Fetches events for System Admin users. This includes actions such as creating, updating, loading, deleting, and more of items such as sheets, reports, dashboards, attachments, and users in your Smartsheet organization account. See Event types for the complete event listing, details, and example objects. > Who can use this operation? > > - Plans: Requires the Event Reporting premium add-on available for Enterprise and Advanced Work Management plans only. > - Permissions: System Admin > Note: You must specify exactly one of the query parameters since or streamPosition. Both are optional individually, but one is required. ### List filtered events - [POST /filteredEvents](https://developers.smartsheet.com/api/smartsheet/openapi/events/list-filtered-events.md): Fetches events related to given sheets and workspaces for non-admin users. See Event types for the complete event listing, details, and example objects. > Who can use this operation? > > - Plans: Requires the Event Reporting premium add-on available for Enterprise and Advanced Work Management plans only. > - Permissions: Non-admin users who have access to given sheets or workspaces. ## Favorites Smartsheet allows users to "star" dashboards, folders, reports, sheets, workspaces, and other objects on their Home tab to mark them as favorites. These API operations allow you to access the user's favorite API-supported objects, as well as create and delete favorites. NOTE: For documentation purposes, "favoriteType" is a placeholder ENUM for the various types of UI elements you can flag as a favorite. In sample code, when you see "{favoriteType}", just replace it with one of the following values: * dashboard or dashboards (aka Sight or Sights) * folder or folders * report or reports * sheet or sheets * template or templates * workspace or workspaces ### Get favorites - [GET /favorites](https://developers.smartsheet.com/api/smartsheet/openapi/favorites/get-favorites.md): Gets a list of all of the user's favorite items. > Note: For pagination guidance, refer to Pagination. ### Add favorites - [POST /favorites](https://developers.smartsheet.com/api/smartsheet/openapi/favorites/add-favorite.md): Adds one or more favorite items for the current user. This operation supports both single-object and bulk semantics. For more information, see Optional Bulk Operations. If called with a single Favorite object, and that favorite already exists, error code 1129 is returned. If called with an array of Favorite objects, any objects specified in the array that are already marked as favorites are ignored and omitted from the response. ### Delete multiple favorites - [DELETE /favorites/{favoriteType}](https://developers.smartsheet.com/api/smartsheet/openapi/favorites/delete-favorites-by-type.md): Deletes all favorites with the same type for the user. ### Delete favorite - [DELETE /favorites/{favoriteType}/{favoriteId}](https://developers.smartsheet.com/api/smartsheet/openapi/favorites/delete-favorites-by-type-and-id.md): Deletes a single favorite from the user's list of favorite items by type and ID. ### Is favorite - [GET /favorites/{favoriteType}/{favoriteId}](https://developers.smartsheet.com/api/smartsheet/openapi/favorites/is-favorite.md): Checks whether an item has been tagged as a favorite for the current user by type and ID. ## Folders A folder can exist in a user's **Sheets** folder [Home](/api/smartsheet/openapi/home), in a [folder](/api/smartsheet/openapi/folders), or in a [workspace](/api/smartsheet/openapi/workspaces). ### Delete folder - [DELETE /folders/{folderId}](https://developers.smartsheet.com/api/smartsheet/openapi/folders/delete-folder.md): Deletes a folder. ### Update folder - [PUT /folders/{folderId}](https://developers.smartsheet.com/api/smartsheet/openapi/folders/update-folder.md): Updates a folder. ### Get folder metadata - [GET /folders/{folderId}/metadata](https://developers.smartsheet.com/api/smartsheet/openapi/folders/get-folder-metadata.md): Gets the metadata of a folder. ### List folder children - [GET /folders/{folderId}/children](https://developers.smartsheet.com/api/smartsheet/openapi/folders/get-folder-children.md): Retrieves a paginated list of immediate child resources within a specified folder. Key Characteristics - Shallow representation: It returns metadata for the direct children only, rather than the full content or nested sub-structures. - Filtered by type: The results are restricted to the resource types defined in the childrenResourceTypes query parameter. - Paginated: The response provides a page of results, implying that for large folders, multiple requests may be necessary to view all children. > Note: For pagination guidance, refer to Token-based pagination. ### Copy folder - [POST /folders/{folderId}/copy](https://developers.smartsheet.com/api/smartsheet/openapi/folders/copy-folder.md): Copies a folder. > Important: This operation doesn't copy cell history. ### Create folder - [POST /folders/{folderId}/folders](https://developers.smartsheet.com/api/smartsheet/openapi/folders/create-folder-folder.md): Creates a new folder inside an existing folder. ### Move folder - [POST /folders/{folderId}/move](https://developers.smartsheet.com/api/smartsheet/openapi/folders/move-folder.md): Moves a folder. ### Get folder (deprecated) - [GET /folders/{folderId}](https://developers.smartsheet.com/api/smartsheet/openapi/folders/get-folder.md): Gets a Folder object. > Important: We've set a 60 requests per minute per API token limit for this operation. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be removed. See the Get folder metadata and the List folder children endpoints for replacement functionality. ### List folders (deprecated) - [GET /folders/{folderId}/folders](https://developers.smartsheet.com/api/smartsheet/openapi/folders/list-folders.md): Gets a list of folders in a given folder. The list contains an abbreviated Folder object for each folder. > Note: For pagination guidance, refer to Pagination. > DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be removed. See the List folder children endpoint for replacement functionality. ## Group Members A group member is a user that belongs to a [group](/api/smartsheet/openapi/groups). ### Add group members - [POST /groups/{groupId}/members](https://developers.smartsheet.com/api/smartsheet/openapi/groupmembers/add-group-members.md): Adds one or more members to a group. _This operation supports both single-object and bulk semantics. For more information, see Optional Bulk Operations._ If called with a single GroupMember object, and that group member already exists, error code 1129 is returned. If called with an array of GroupMember objects, any users specified in the array that are already group members are ignored and omitted from the response. _This operation is only available to group administrators and system administrators._ ### Delete group members - [DELETE /groups/{groupId}/members/{userId}](https://developers.smartsheet.com/api/smartsheet/openapi/groupmembers/delete-group-members.md): Removes a member from a group. _This operation is only available to group administrators and system administrators._ ## Groups A group is a collection of [group members](/api/smartsheet/openapi/groupmembers). ### List org groups - [GET /groups](https://developers.smartsheet.com/api/smartsheet/openapi/groups/list-groups.md): Gets a list of all groups in an organization account. To fetch the members of an individual group, use the Get Group operation. > Note: For pagination guidance, refer to Pagination. ### Add group - [POST /groups](https://developers.smartsheet.com/api/smartsheet/openapi/groups/add-group.md): Creates a new group. _This operation is only available to group administrators and system administrators._ ### Get group - [GET /groups/{groupId}](https://developers.smartsheet.com/api/smartsheet/openapi/groups/get-group.md): Gets information about an array of Group Members for the group specified in the URL. ### Update group - [PUT /groups/{groupId}](https://developers.smartsheet.com/api/smartsheet/openapi/groups/update-group.md): Updates the Group specified in the URL. _This operation is only available to group administrators and system administrators._ ### Delete group - [DELETE /groups/{groupId}](https://developers.smartsheet.com/api/smartsheet/openapi/groups/delete-group.md): Deletes the group specified in the URL. _This operation is only available to group administrators and system administrators._ ## Home In the Smartsheet UI, the "Home" tab shows all objects a user has access to, including dashboards (also called Sights in the API), folders, reports, sheets, templates, and workspaces. > **Note:** The GET /home endpoint is deprecated. Use GET /folders/personal to get shared items and GET /workspaces/ to get workspaces.

Home Folders

For details about working with folders in the user's **Sheets** folder (that is, at the Home level), see [Folders](/api/smartsheet/openapi/folders).

Home Sheets

For details about working with sheets in the user's **Sheets** folder (that is, at the Home level), see [Sheets](/api/smartsheet/openapi/sheets). ### List contents (deprecated) - [GET /folders/personal](https://developers.smartsheet.com/api/smartsheet/openapi/home/list-home-contents.md): Gets a nested list of all Home objects shared to the user, including dashboards, folders, reports, sheets, and templates, as shown on the "Home" tab. DEPRECATED - This endpoint is being removed. To adapt to this change, please see Migrate from using the Sheets folder. ### List folders in home (deprecated) - [GET /home/folders](https://developers.smartsheet.com/api/smartsheet/openapi/home/home-list-folders.md): Lists the folders in your Sheets folder. The list contains an abbreviated Folder object for each folder. > Note: For pagination guidance, refer to Pagination. DEPRECATED - The Sheets folder is being replaced by workspaces. To adapt to this change, please see Migrate from using the Sheets folder. ### Create folder (deprecated) - [POST /home/folders](https://developers.smartsheet.com/api/smartsheet/openapi/home/create-home-folder.md): Creates a new folder. DEPRECATED - This endpoint is being removed. To adapt to this change, please see Migrate from using the Sheets folder. ## Imports Import CSV or XLSX data into a new sheet. ### Import sheet into folder - [POST /folders/{folderId}/sheets/import](https://developers.smartsheet.com/api/smartsheet/openapi/imports/import-sheet-into-folder.md): Imports CSV or XLSX data into a new sheet in the specified folder. Note the following: * Both sheetName and the file name must use ASCII characters. * The source data must be basic text. To include rich formula data, import and create a sheet first, and then use Update Rows. To work with images, see Cell Images. * XLS is not supported. You must use XLSX. * Hierarchical relationships between rows in an external file won't import. ### Import sheet into workspace - [POST /workspaces/{workspaceId}/sheets/import](https://developers.smartsheet.com/api/smartsheet/openapi/imports/import-sheet-into-workspace.md): Imports CSV or XLSX data into a new sheet in the specified workspace. Note the following: * Both sheetName and the file name must use ASCII characters. * The source data must be basic text. To include rich formula data, import and create a sheet first, and then use Update Rows. To work with images, see Cell Images. * XLS is not supported. You must use XLSX. * Hierarchical relationships between rows in an external file won't import. ### Import sheet from CSV / XLSX (deprecated) - [POST /sheets/import](https://developers.smartsheet.com/api/smartsheet/openapi/imports/import-sheet-into-sheets-folder.md): Imports CSV or XLSX data into a new sheet in the top-level "Sheets" folder. Note the following: * Both sheetName and the file name must use ASCII characters. * The source data must be basic text. To include rich formula data, import and create a sheet first, and then use Update Rows. To work with images, see Cell Images. * XLS is not supported. You must use XLSX. * Hierarchical relationships between rows in an external file won't import. DEPRECATED - The Sheets folder is being replaced by workspaces. To adapt to this change, please see Migrate from using the Sheets folder. ## Proofs A proof is a container that holds attachments and comments. Limited to one proof and its versions per row. A sheet can have multiple proofs. ### List proofs - [GET /sheets/{sheetId}/proofs](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-getallproofs.md): Gets a list of all proofs for a given sheet. > Note: For pagination guidance, refer to Pagination. ### Get proof - [GET /sheets/{sheetId}/proofs/{proofId}](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-get.md): Gets the proof specified in the URL. Returns the proof, which is optionally populated with discussion and attachment objects. ### Delete proof - [DELETE /sheets/{sheetId}/proofs/{proofId}](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-delete.md): Deletes the proof including all versions. The proofId must be for the original version. ### Update proof status - [PUT /sheets/{sheetId}/proofs/{proofId}](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-update.md): Sets the proof status as either complete or incomplete. ### List proof attachments - [GET /sheets/{sheetId}/proofs/{proofId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-listattachments.md): Gets a list of all attachments that are in the proof, excluding discussion-level attachments in the proof. > Note: For pagination guidance, refer to Pagination. ### Attach file to proof - [POST /sheets/{sheetId}/proofs/{proofId}/attachments](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-attachtoproof.md): Attaches a file to the proof. > Important: The file size limit is 30mb. > Note: Posting a file attachment is resource-intensive and is limited to 30 requests per minute per API token. For details, see Rate limiting. ### List proof discussions - [GET /sheets/{sheetId}/proofs/{proofId}/discussions](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-listdiscussions.md): Gets a list of all discussions that are in the proof. > Note: For pagination guidance, refer to Pagination. ### Create proof discussion - [POST /sheets/{sheetId}/proofs/{proofId}/discussions](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-creatediscussion.md): Creates a discussion on a proof. ### List proof request actions - [GET /sheets/{sheetId}/proofs/{proofId}/requestactions](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-listrequestactions.md): Gets a summarized list of all request actions associated with the specified proof. > Note: For pagination guidance, refer to Pagination. ### Delete proof requests - [DELETE /sheets/{sheetId}/proofs/{proofId}/requests](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-deleteproofrequests.md): Deletes all proof requests in a proof. ### Create proof request - [POST /sheets/{sheetId}/proofs/{proofId}/requests](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-createproofrequests.md): Creates a proof request. ### List proof versions - [GET /sheets/{sheetId}/proofs/{proofId}/versions](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-getversions.md): Gets a list of all versions of the given proofId in order from newest to oldest. > Note: For pagination guidance, refer to Pagination. ### Delete proof version - [DELETE /sheets/{sheetId}/proofs/{proofId}/versions](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-deleteversion.md): Deletes a proof version. Proof ID must be a current version proof ID. ### Create proof version - [POST /sheets/{sheetId}/proofs/{proofId}/versions](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-createversion.md): Creates a proof version. Proof ID must be for the original proof. ### Create proof - [POST /sheets/{sheetId}/rows/{rowId}/proofs](https://developers.smartsheet.com/api/smartsheet/openapi/proofs/proofs-create.md): Creates a proof on a row. ## Reports A report is a filtered view of the data from one or more sheets. Like a sheet, a report is comprised of columns, rows, and cells, and may optionally contain attachments and discussions. A report is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

Report Attachments

For details about working with a report's attachments, see [Attachments](/api/smartsheet/openapi/attachments).

Report Cells

For details about working with a report's cells, see [Cells](/api/smartsheet/openapi/cells).

Report Columns

For details about working with a report's columns, see [Columns](/api/smartsheet/openapi/columns).

Report Discussions

For details about working with a report's discussions, see [Discussions](/api/smartsheet/openapi/discussions).

Report Rows

For details about working with a report's rows, see [Rows](/api/smartsheet/openapi/rows). ### List reports - [GET /reports](https://developers.smartsheet.com/api/smartsheet/openapi/reports/getreports.md): List all Reports accessible to the user. > Note: For pagination guidance, refer to Pagination. ### Get report - [GET /reports/{reportId}](https://developers.smartsheet.com/api/smartsheet/openapi/reports/getreport.md): Gets a report based on the specified ID ### Send report via email - [POST /reports/{reportId}/emails](https://developers.smartsheet.com/api/smartsheet/openapi/reports/sendreportviaemail.md): Sends the report as a PDF attachment via email to the designated recipients ### Gets a report's publish settings - [GET /reports/{reportId}/publish](https://developers.smartsheet.com/api/smartsheet/openapi/reports/getreportpublish.md): Get a Report's publish settings based on the specified ID ### Set a report's publish status - [PUT /reports/{reportId}/publish](https://developers.smartsheet.com/api/smartsheet/openapi/reports/setreportpublish.md): Sets the publish status of the report and returns the new status, including the URL of any enabled publishing. ### Share report (deprecated) - [POST /reports/{reportId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/reports/share-report.md): Shares a Report with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List report shares (deprecated) - [GET /reports/{reportId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/reports/list-report-shares.md): Gets a list of all users and groups to whom the specified Report is shared, and their access level. This operation supports query string parameters for pagination of results. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get report share (deprecated) - [GET /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/reports/share-report-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete report share (deprecated) - [DELETE /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/reports/delete-report-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update report share (deprecated) - [PUT /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/reports/update-report-share.md): Updates the access level of a user or group for the specified report. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Share report (deprecated) - [POST /reports/{reportId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-report.md): Shares a Report with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List report shares (deprecated) - [GET /reports/{reportId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-report-shares.md): Gets a list of all users and groups to whom the specified Report is shared, and their access level. This operation supports query string parameters for pagination of results. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get report share (deprecated) - [GET /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-report-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete report share (deprecated) - [DELETE /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-report-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update report share (deprecated) - [PUT /reports/{reportId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-report-share.md): Updates the access level of a user or group for the specified report. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ## Rows A row is a component of a sheet or report. Each row is composed of a collection of cells, and may optionally contain discussions or attachments. A row is comprised of a collection of cells, and may optionally contain attachments and discussions.

Row Attachments

For details about working with a row's attachments, see [Attachments](/api/smartsheet/openapi/attachments).

Row Cells

For details about working with a row's cells, see [Cells](/api/smartsheet/openapi/cells). For details about working with images in cells, see [Cell Images](/api/smartsheet/openapi/cellimages).

Row Discussions

For details about working with a row's discussions, see [Discussions](/api/smartsheet/openapi/discussions).

Row Include Flags

Endpoints which return rows (for example, [Get Sheet](/api/smartsheet/openapi/sheets/getsheet), [Get Row](/api/smartsheet/openapi/rows/row-get)) support the optional **include** query string parameter. If specified, the value of the **include** parameter is a comma-delimited list of flags that indicate additional attributes to be included in each [Row object](/api/smartsheet/openapi/rows/row) within the response. Include Flag | Description | -------------|-------| **attachments** | Includes row **attachments** array.
To include discussion attachments, both **attachments** and **discussions** must be present in the include list. **columnType** | Includes **columnType** attribute in the row's [cells](/api/smartsheet/openapi/cells/cell) indicating the type of the column the cell resides in. **discussions** | Includes row **discussions** array.
To include discussion attachments, both **attachments** and **discussions** must be present in the include list. **filters** | Includes **filteredOut** attribute indicating if the row should be displayed or hidden according to the sheet's filters. **format** | Includes **format** attribute on the row, its cells, or summary fields. See [Cell formatting](/api/smartsheet/guides/advanced-topics/cell-formatting). **objectValue** | Includes **objectValue** attribute on cells containing values. For more information see [Cell Reference](/api/smartsheet/openapi/cells). **rowPermalink** | Includes **permalink** attribute that represents a direct link to the [row](/api/smartsheet/openapi/rows/row) in the Smartsheet application. **rowWriterInfo** | **DEPRECATED** Includes **createdBy** and **modifiedBy** attributes on the row, indicating the row's creator, and last modifier. **writerInfo** | Includes **createdBy** and **modifiedBy** attributes on the row or summary fields, indicating the row or summary field's creator, and last modifier.

Specify Row Location

When you [add a row](/api/smartsheet/openapi/rows/rows-addtosheet), the default behavior is for Smartsheet to put the new row at the bottom of the sheet. And when you [update a row](/api/smartsheet/openapi/rows/update-rows), the default behavior is to keep the row where it is. It is not necessary to use a location-specifier attribute if you want the default behavior. To specify a location for new or updated rows other than the defaults, use the table below for reference. The table details possible row locations and provides JSON examples to help you construct one or more [Row objects](/api/smartsheet/openapi/rows/row) with location-specifier attributes. Note the following restrictions: * Use only one location-specifier attribute per request, unless you use **parentId** and **toBottom** or **siblingId** and **above**. * If you specify multiple rows in the request, all rows must have the same location-specifier attributes. * If you specify the **parentId** attribute, you cannot also specify the **siblingId** attribute. * If you specify the **siblingId** attribute, you cannot also specify the **parentId**, **toTop**, or **toBottom** attributes. * If you want to indent or outdent multiple rows, use the **parentId** attribute. Destination | Row Attributes | Examples | -------|--------|--------| Top of a sheet | **toTop** | ```{"toTop": true}``` Bottom of a sheet | **toBottom** | ```{"toBottom": true}``` Top of an indented section a.k.a., first child row | **parentId** | ```{"parentId": 8896508249565060}``` Bottom of an indented section a.k.a., last child row | **parentId** +
**toBottom** | ```{"parentId": 8896508249565060, "toBottom": true}``` Below a specific row, at the same indent level | **siblingId** | ```{"siblingId": 8896508249565060}``` Above a specific row, at the same indent level | **siblingId** +
**above** | ```{"siblingId": 8896508249565060, "above": true}``` Indent one existing row, must have a value of "1" | **indent** | ```{"indent": 1}``` Outdent one existing row, must have a value of "1" | **outdent** | ```{"outdent": 1}``` ### Add rows - [POST /sheets/{sheetId}/rows](https://developers.smartsheet.com/api/smartsheet/openapi/rows/rows-addtosheet.md): Inserts one or more rows into the sheet specified in the URL. If you want to insert the rows in any position but the default, use location-specifier attributes (that is, toTop, toBottom, parentId, siblingId, above, indent, outdent). See language tabs for variations in syntax. Note: This operation does not add rows with cells that have images. However, you can upload an image to a cell after the cell exists in a sheet. To do so, call the operation described in the Add Image to Cell page. This operation supports both single-object and bulk semantics. For more information, see Optional Bulk Operations. ### Delete rows - [DELETE /sheets/{sheetId}/rows](https://developers.smartsheet.com/api/smartsheet/openapi/rows/delete-rows.md): Deletes one or more rows from the sheet specified in the URL. ### Update rows - [PUT /sheets/{sheetId}/rows](https://developers.smartsheet.com/api/smartsheet/openapi/rows/update-rows.md): Updates cell values in the specified rows, expands/collapses the specified rows, or modifies the position of specified rows (including indenting/outdenting). For detailed information about changing row positions, see location-specifier attributes. Note: This operation does not handle adding images to cells. However, you can upload an image to a cell by calling the operation described in the Add Image to Cell page. ### Send rows via email - [POST /sheets/{sheetId}/rows/emails](https://developers.smartsheet.com/api/smartsheet/openapi/rows/rows-send.md): Sends one or more rows via email. ### Copy rows to another sheet - [POST /sheets/{sheetId}/rows/copy](https://developers.smartsheet.com/api/smartsheet/openapi/rows/copy-rows.md): Copies rows from the sheet specified in the URL to (the bottom of) another sheet. ### Move rows to another sheet - [POST /sheets/{sheetId}/rows/move](https://developers.smartsheet.com/api/smartsheet/openapi/rows/move-rows.md): Moves rows from the sheet specified in the URL to (the bottom of) another sheet. ### Get row - [GET /sheets/{sheetId}/rows/{rowId}](https://developers.smartsheet.com/api/smartsheet/openapi/rows/row-get.md): Gets the row specified in the URL. ### Sort rows in sheet - [POST /sheets/{sheetId}/sort](https://developers.smartsheet.com/api/smartsheet/openapi/rows/rows-sort.md): Sorts the rows of a sheet, either in ascending or descending order. ## Search Search a specific sheet or search across all sheets that a user can access. If you have not used the public API in a while, we will need to provision your data. This could take up to 24 hours so please check back later! ### Search everything - [GET /search](https://developers.smartsheet.com/api/smartsheet/openapi/search/list-search.md): Searches all sheets that the user can access, for the specified text. > Important: If you have't used the public API in a while, we will need to provision your data. This could take up to 24 hours so please check back later! ### Search sheet - [GET /search/sheets/{sheetId}](https://developers.smartsheet.com/api/smartsheet/openapi/search/list-search-sheet.md): Gets a list of the user's search results in a sheet, based on a query. The list contains an abbreviated row object for each query-matching row in the sheet. > Important: If you have't used the public API in a while, we will need to provision your data. This could take up to 24 hours so please check back later! > Note: Newly created or recently updated data may not be immediately discoverable via search. ## Server Info For developer convenience, the Smartsheet API provides access to application constants. ### Gets application constants - [GET /serverinfo](https://developers.smartsheet.com/api/smartsheet/openapi/serverinfo/serverinfo-get.md): Gets application constants. ## Sheets A sheet can exist in a user's **Sheets** folder ([Home](/api/smartsheet/openapi/home)), in a [folder](/api/smartsheet/openapi/folders), or in a [workspace](/api/smartsheet/openapi/workspaces). It is comprised of columns, rows, and cells, and may optionally contain attachments and discussions. A sheet is comprised of columns, rows, and cells, and may optionally contain attachments and discussions.

Sheet Attachments

For details about working with a sheet's attachments, see [Attachments](/api/smartsheet/openapi/attachments).

Sheet Cells

For details about working with a sheet's cells, see [Cells](/api/smartsheet/openapi/cells). For details about working with images in cells, see [Cell Images](/api/smartsheet/openapi/cellimages).

Sheet Columns

For details about working with a sheet's columns, see [Columns](/api/smartsheet/openapi/columns).

Sheet Discussions

There are two ways to get discussion-related information for a sheet: Operation | Returns ----------|----------| [Get Sheet](/api/smartsheet/openapi/sheets/getsheet)
(with **include** parameter value **discussions**) | Response does not contain the comments that comprise each discussion. [List Discussions](/api/smartsheet/openapi/discussions/discussions-list)
(with **include** parameter value **comments**) | Response contains the comments that comprise each discussion. For more information about working with a sheet's discussions, see [Discussions](/api/smartsheet/openapi/discussions).

Sheet Rows

For details about working with a sheet's rows, see [Rows](/api/smartsheet/openapi/rows). ### Share sheet (deprecated) - [POST /sheets/{sheetId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-sheet.md): Shares a sheet with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List sheet shares (deprecated) - [GET /sheets/{sheetId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-sheet-shares.md): Gets a list of all users and groups to whom the specified Sheet is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get sheet share (deprecated) - [GET /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-sheet-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete sheet share (deprecated) - [DELETE /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-sheet-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update sheet share (deprecated) - [PUT /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-sheet-share.md): Updates the access level of a user or group for the specified sheet. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Create sheet in folder - [POST /folders/{folderId}/sheets](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/create-sheet-in-folder.md): Creates a sheet from scratch or from the specified template in the specified folder. ### List sheets - [GET /sheets](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/list-sheets.md): Gets a list of all sheets that the user has access to. The list contains an abbreviated Sheet object for each sheet. > Note: For pagination guidance, refer to Pagination. ### Get sheet - [GET /sheets/{sheetId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/getsheet.md): Gets a sheet in the format specified, based on the sheet Id. ### Delete sheet - [DELETE /sheets/{sheetId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/deletesheet.md): Deletes the sheet specified in the URL. ### Update sheet - [PUT /sheets/{sheetId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/updatesheet.md): Updates the sheet specified in the URL. To modify sheet contents, see Add Rows, Update Rows, Add Columns, and Update Column. This operation can be used to update an individual user's sheet settings. If the request body contains only the userSettings attribute, this operation may be performed even if the user only has read-only access to the sheet (for example, the user has viewer permissions or the sheet is read-only). ### Copy sheet - [POST /sheets/{sheetId}/copy](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/copy-sheet.md): Creates a copy of the specified sheet. ### Send sheet via email - [POST /sheets/{sheetId}/emails](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/sheet-send.md): Sends the sheet as a PDF attachment via email to the designated recipients. ### Move sheet - [POST /sheets/{sheetId}/move](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/move-sheet.md): Moves the specified sheet to a new location. When a sheet that is shared to one or more users and/or groups is moved into or out of a workspace, those sheet-level shares are preserved. ### Get sheet publish status - [GET /sheets/{sheetId}/publish](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/get-sheetpublish.md): Gets the sheet's 'Publish' settings. ### Set sheet publish status - [PUT /sheets/{sheetId}/publish](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/set-sheetpublish.md): Sets the publish status of the sheet and returns the new status, including the URLs of any enabled publishings. ### Get sheet version - [GET /sheets/{sheetId}/version](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/get-sheetversion.md): Gets the sheet version without loading the entire sheet. The following actions increment sheet version: * add/modify cell value * add/modify discussion/comment * add/modify row * add/remove/update version attachment * cell updated via cell link * change formatting ### List org sheets - [GET /users/sheets](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/list-org-sheets.md): Gets a summarized list of all sheets owned by the members of the organization account. > Who can use this operation? > > Permissions: System Admin *_You may use the query string parameter numericDates with a value of true to enable strict parsing of dates in numeric format. See [Dates and Times](/api/smartsheet/guides/basics/dates-and-times) for more information._ ### Create sheet in workspace - [POST /workspaces/{workspaceId}/sheets](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/create-sheet-in-workspace.md): Creates a sheet from scratch or from the specified template at the top-level of the specified workspace. For subfolders, use Create Sheet in Folder. ### Create sheet in "Sheets" folder (deprecated) - [POST /sheets](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/create-sheet-in-sheets-folder.md): Creates a sheet from scratch or from the specified template in the user's Sheets folder (Home). For subfolders, use Create Sheet in Folder. DEPRECATED - The Sheets folder is being replaced by workspaces. To adapt to this change, please see Migrate from using the Sheets folder. ### Share sheet (deprecated) - [POST /sheets/{sheetId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/share-sheet.md): Shares a sheet with the specified users and groups. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List sheet shares (deprecated) - [GET /sheets/{sheetId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/list-sheet-shares.md): Gets a list of all users and groups to whom the specified Sheet is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get sheet share (deprecated) - [GET /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/share-sheet-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete sheet share (deprecated) - [DELETE /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/delete-sheet-share.md): Deletes the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update sheet share (deprecated) - [PUT /sheets/{sheetId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/update-sheet-share.md): Updates the access level of a user or group for the specified sheet. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ## Workspaces Similar to a folder, a workspace is a place where you can store dashboards, reports, sheets, and templates to keep them organized. A workspace offers more functionality than a folder because you can set up sharing permissions and branding (a logo and a color scheme) at the workspace-level and a workspace can contain folders so that you can keep things within it organized. As new items are added to the workspace, they'll automatically inherit the sharing permissions and branding applied to that workspace.

Workspace Folders

For details about working with folders in a workspace, see [Folders](/api/smartsheet/openapi/folders).

Workspace Sheets

For details about working with sheets in a workspace, see [Sheets](/api/smartsheet/openapi/sheets). ### Share workspace (deprecated) - [POST /workspaces/{workspaceId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-workspace.md): Shares a Workspace with the specified users and groups. This operation supports both single-object and bulk semantics. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List workspace shares (deprecated) - [GET /workspaces/{workspaceId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/list-workspace-shares.md): Gets a list of all users and groups to whom the specified Workspace is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get workspace share (deprecated) - [GET /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/share-workspace-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete workspace share (deprecated) - [DELETE /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/delete-workspace-share.md): Deletes the share specified in the URL. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update workspace share (deprecated) - [PUT /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/sharing/update-workspace-share.md): Updates the access level of a user or group for the specified workspace. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List workspaces - [GET /workspaces](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/list-workspaces.md): Retrieves a list of workspaces that the user has access to. It returns metadata for the workspaces only and doesn't include nested sub-structures. > Tip: Set paginationType=token to use token-based pagination. ### Create workspace - [POST /workspaces](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/create-workspace.md): Creates a new workspace. ### Delete workspace - [DELETE /workspaces/{workspaceId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/delete-workspace.md): Deletes a workspace. ### Update workspace - [PUT /workspaces/{workspaceId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/update-workspace.md): Updates a workspace. ### Get workspace metadata - [GET /workspaces/{workspaceId}/metadata](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/get-workspace-metadata.md): Gets the metadata of a workspace. ### List workspace children - [GET /workspaces/{workspaceId}/children](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/get-workspace-children.md): Retrieves a paginated list of immediate child resources within a specified workspace. Key Characteristics - Shallow representation: It returns metadata for the direct children only, rather than the full content or nested sub-structures. - Filtered by type: The results are restricted to the resource types defined in the childrenResourceTypes query parameter. - Paginated: The response provides a page of results, implying that for large workspaces, multiple requests may be necessary to view all children. > Note: For pagination guidance, refer to Token-based pagination. ### Copy workspace - [POST /workspaces/{workspaceId}/copy](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/copy-workspace.md): Copies a workspace. > Important: This operation doesn't copy cell history. ### Create folder in workspace - [POST /workspaces/{workspaceId}/folders](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/create-workspace-folder.md): Creates a new folder in the workspace. ### Get workspace (deprecated) - [GET /workspaces/{workspaceId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/get-workspace.md): Gets a Workspace object. > Important: We've set a 60 requests per minute per API token limit for this operation. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be removed. See the Get workspace metadata and the Get workspace children endpoints for replacement functionality. ### List workspace folders (deprecated) - [GET /workspaces/{workspaceId}/folders](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/get-workspace-folders.md): Lists a workspace's folders. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be removed. See the Get workspace children endpoint for replacement functionality. ### Share workspace (deprecated) - [POST /workspaces/{workspaceId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/share-workspace.md): Shares a Workspace with the specified users and groups. This operation supports both single-object and bulk semantics. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### List workspace shares (deprecated) - [GET /workspaces/{workspaceId}/shares](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/list-workspace-shares.md): Gets a list of all users and groups to whom the specified Workspace is shared, and their access level. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Get workspace share (deprecated) - [GET /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/share-workspace-get.md): Gets the share specified in the URL. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Delete workspace share (deprecated) - [DELETE /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/delete-workspace-share.md): Deletes the share specified in the URL. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ### Update workspace share (deprecated) - [PUT /workspaces/{workspaceId}/shares/{shareId}](https://developers.smartsheet.com/api/smartsheet/openapi/workspaces/update-workspace-share.md): Updates the access level of a user or group for the specified workspace. _This operation is only available to system administrators._ DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. Please refer to the Changelog entry for more details. ## Sheet Summary A sheet summary allows users to define, organize, and report on custom project and business metadata. Sheet summary is only available to customers with business or enterprise plans. ### Get sheet summary - [GET /sheets/{sheetId}/summary](https://developers.smartsheet.com/api/smartsheet/openapi/sheetsummary/list-summary-fields.md): Returns object containing array of summary fields. Allows for pagination of results. ### Get summary fields - [GET /sheets/{sheetId}/summary/fields](https://developers.smartsheet.com/api/smartsheet/openapi/sheetsummary/list-summary-fields-paginated.md): Returns object containing array of summary fields. > Note: For pagination guidance, refer to Pagination. ### Update summary fields - [PUT /sheets/{sheetId}/summary/fields](https://developers.smartsheet.com/api/smartsheet/openapi/sheetsummary/update-summary-fields.md): Updates the summary fields for the given sheet. ### Delete summary fields - [DELETE /sheets/{sheetId}/summary/fields](https://developers.smartsheet.com/api/smartsheet/openapi/sheetsummary/delete-summary-fields.md): Deletes summary fields from the specified sheet. ### Add summary fields - [POST /sheets/{sheetId}/summary/fields](https://developers.smartsheet.com/api/smartsheet/openapi/sheetsummary/add-summary-fields.md): Creates one or more summary fields for the specified sheet. ### Add image to sheet summary - [POST /sheets/{sheetId}/summary/fields/{fieldId}/images](https://developers.smartsheet.com/api/smartsheet/openapi/sheetsummary/add-image-summaryfield.md): Adds an image to the summary field. ## Templates A template can be used to create a sheet, as described for the [Create sheet in folder](/api/smartsheet/openapi/sheets/create-sheet-in-folder) endpoint and the [Create sheet in workspace](/api/smartsheet/openapi/sheets/create-sheet-in-workspace) endpoint. ### List user-created templates (deprecated) - [GET /templates](https://developers.smartsheet.com/api/smartsheet/openapi/templates/templates-list.md): Gets a list of user-created templates that the user has access to. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. See this Changelog entry for details on alternatives. ### List public templates (deprecated) - [GET /templates/public](https://developers.smartsheet.com/api/smartsheet/openapi/templates/templates-listpublic.md): Gets a list of public templates that the user has access to. > Note: For pagination guidance, refer to Pagination. DEPRECATED - As early as the sunset date specified in this Changelog entry, this endpoint will be discontinued. ## Tokens The Smartsheet API utilizes OAuth 2.0 for authentication and authorization. An Authorization HTTP header containing an access token is required to authenticate all API requests except for the requests to GET Access Token or Refresh Access Token. For more information, see Authentication. ### Gets or refreshes an access token - [POST /token](https://developers.smartsheet.com/api/smartsheet/openapi/tokens/tokens-getorrefresh.md): Gets or refreshes an access token, as part of the OAuth process. ### Revoke access token - [DELETE /token](https://developers.smartsheet.com/api/smartsheet/openapi/tokens/tokens-delete.md): Revokes the access token used to make this request. The access token is no longer valid, and subsequent API calls made using the token fail. ## Update Requests Send update requests to get updated by any collaborator on key rows, regardless of whether they have a Smartsheet account or are shared to the sheet. ### Lists sent update requests - [GET /sheets/{sheetId}/sentupdaterequests](https://developers.smartsheet.com/api/smartsheet/openapi/updaterequests/sentupdaterequests-list.md): Lists summarized sent update requests on the sheet. For comprehensive details on a sent update request, refer to Get sent update request. > Note: For pagination guidance, refer to Pagination. ### Get sent update request - [GET /sheets/{sheetId}/sentupdaterequests/{sentUpdateRequestId}](https://developers.smartsheet.com/api/smartsheet/openapi/updaterequests/sentupdaterequest-get.md): Gets the specified sent update request on the sheet. ### Delete sent update request - [DELETE /sheets/{sheetId}/sentupdaterequests/{sentUpdateRequestId}](https://developers.smartsheet.com/api/smartsheet/openapi/updaterequests/sentupdaterequest-delete.md): Deletes the specified sent update request. Delete operation is supported only when the specified sent update request is in the pending status. Deleting a sent update request that was already completed by recipient is not allowed. ### List update requests - [GET /sheets/{sheetId}/updaterequests](https://developers.smartsheet.com/api/smartsheet/openapi/updaterequests/updaterequests-list.md): Gets a summarized list of all update requests that have future schedules associated with the specified sheet. Only the following fields are returned in the response: * id * ccMe * createdAt * message * modifiedAt * schedule * sendTo * sentBy * subject > Note: For pagination guidance, refer to Pagination. ### Create an update request - [POST /sheets/{sheetId}/updaterequests](https://developers.smartsheet.com/api/smartsheet/openapi/updaterequests/updaterequests-create.md): Creates an update request for the specified rows within the sheet. An email notification (containing a link to the update request) is sent to the specified recipients according to the specified schedule. The recipients of an update request must be specified by using email addresses only. Sending an update request to a group is not supported. The following attributes have the following values when not specified: * ccMe: false * message: Please update the following rows in my online sheet. * subject: Update Request: {Sheet Name} When the Schedule object is not specified, the request is sent to the recipients immediately. If an error occurs because the request specified one or more alternate email addresses, please retry using the primary email address. ### Get an update request - [GET /sheets/{sheetId}/updaterequests/{updateRequestId}](https://developers.smartsheet.com/api/smartsheet/openapi/updaterequests/updaterequests-get.md): Gets the specified update request for the sheet that has a future schedule. The rowIds and columnIds in the returned UpdateRequest object represent the list at the time the update request was created or last modified. The lists may contain Ids of rows or columns that are no longer valid (for example, they have been removed from the sheet). ### Update an update request - [PUT /sheets/{sheetId}/updaterequests/{updateRequestId}](https://developers.smartsheet.com/api/smartsheet/openapi/updaterequests/updaterequests-update.md): Changes the specified update request for the sheet. Making changes to update requests that do not have future scheduled delivery is not allowed. The UpdateRequest object in the request body must specify one or more of the following attributes: * ccMe: Boolean * columnIds: number[] * includeAttachments: Boolean * includeDiscussions: Boolean * message: string * schedule: Schedule object * sendTo: Recipient[] * subject: string If an error occurs because the request specified one or more alternate email addresses, please retry using the primary email address. ### Delete an update request - [DELETE /sheets/{sheetId}/updaterequests/{updateRequestId}](https://developers.smartsheet.com/api/smartsheet/openapi/updaterequests/updaterequests-delete.md): Terminates the future scheduled delivery of the update request specified in the URL. ## Users The users API supports user CRUD operations, seat type operations, and activation/deactivation operations. > **Note:** Users are typically defined by the organization account, and then role within the organization, for example admin.

Users guides

To learn more about user-related resources and how to manage them, see the [Users guide articles](/api/smartsheet/guides/users), including the [Automate user seat type management](/api/smartsheet/guides/users/automate-user-seat-type-management.md) guide. ### List users - [GET /users](https://developers.smartsheet.com/api/smartsheet/openapi/users/list-users.md): Gets a list of users in the organization account. To filter by email, use the optional email query string parameter to specify a list of users' email addresses. For System admins, the following User object attributes are included in the response (else, they are omitted from the response): * admin * groupAdmin * isInternal * licensedSheetCreator * resourceViewer * seatType * seatTypeLastChangedAt * sheetCount (SUNSET) - The sheetCount attribute now holds the value -1 and is included only if the retrieved user's status is ACTIVE. * status > Note: If the API request is submitted by a System Admin of an Enterprise account, and Custom Welcome Screen is enabled, the following User object attributes are included in the response (else, they are omitted from the response): > > customWelcomeScreenViewed (omitted if the user has never viewed the Custom Welcome Screen) > Note: For pagination guidance, refer to Pagination. ### Add user - [POST /users](https://developers.smartsheet.com/api/smartsheet/openapi/users/add-user.md): Adds a user to the organization account. > Who can use this operation? > > Permissions: System Admin If successful, and user auto provisioning (UAP) is on, and user matches the auto provisioning rules, user is added to the org. If UAP is off, or user does not match UAP rules, user is invited to the org and must explicitly accept the invitation to join. > Note: On user model plans, this operation sets licensedSheetCreator to true, regardless of the value provided in the request body. > Note: In some specific scenarios, supplied attributes such as firstName and lastName may be ignored. For example, if you are inviting an existing Smartsheet user to join your organization account, and the invited user has not yet accepted your invitation, any supplied firstName and lastName are ignored. ### Get current user - [GET /users/me](https://developers.smartsheet.com/api/smartsheet/openapi/users/get-current-user.md): Gets the current user. For System Admins, the following UserProfile attributes are included in the response: * customWelcomeScreenViewed (only included when an Enterprise user has viewed the Custom Welcome Screen) * lastLogin (only included if the user has logged in) * sheetCount (Sunset) - The sheetCount attribute now holds the value -1 and is included only if the retrieved user's status is ACTIVE. ### Get user - [GET /users/{userId}](https://developers.smartsheet.com/api/smartsheet/openapi/users/get-user.md): Gets the user specified in the URL. For System Admins, the following UserProfile attributes are included in the response): * admin * customWelcomeScreenViewed (only returned when an Enterprise user has viewed the Custom Welcome Screen) * groupAdmin * lastLogin (only returned if the user has logged in) * licensedSheetCreator * resourceViewer * sheetCount (Sunset) - The sheetCount attribute now holds the value -1 and is included only if the retrieved user's status is ACTIVE. * status ### Remove user from organization - [DELETE /users/{userId}](https://developers.smartsheet.com/api/smartsheet/openapi/users/remove-user.md): Removes the user from your organization. > Who can use this operation? > > Permissions: System Admin > Important: To remove a user from your plan, refer to Remove user from plan. If you have Enterprise Plan Manager enabled, this endpoint removes the user from organizations that inherit from your organization. If you're managing users via an external source, such as an identity provider (IdP) or directory integration (DI) provider, you must use that source to remove users. Okta and Azure AD are examples of external sources. ### Update user - [PUT /users/{userId}](https://developers.smartsheet.com/api/smartsheet/openapi/users/update-user.md): Updates attributes of the specified user. > Who can use this operation? > > Permissions: System Admin. To modify a user who belongs to a user model organization, you must also be a member of that same organization. Licensed sheet creator constraints - On the user model, you can only update licensedSheetCreator for a System Admin user (admin: true). - You can't revoke the licensed sheet creator status (that is, set licensedSheetCreator to false) for a user who is either a Group Admin (groupAdmin: true) or a Resource Viewer (resourceViewer: true). ### Deactivate user - [POST /users/{userId}/deactivate](https://developers.smartsheet.com/api/smartsheet/openapi/users/deactivate-user.md): Deactivates the user associated with the current Smartsheet plan, blocking the user from using Smartsheet in any way. Deactivating a user does not affect their existing permissions on owned or shared items. Optionally, with Enterprise Plan Manager (EPM) enabled, you can deactivate a user from child organizations. > Who can use this operation? > > Permissions: System Admin > > This operation is unavailable for Smartsheet Gov. Attempting to deactivate a user that matches any of the following criteria results in an error: - The user's primary email address belongs to an ISP domain (e.g., gmail.com, yahoo.com, outlook.com). For example, see the common ISP domains listed below. - The user's primary email address is unassociated with the current Smartsheet plan domain(s). - The user is managed by an external source, such as an identity provider (IdP) or directory integration (DI) provider. External source examples include Okta and Azure AD. Deactivating such a user can only be done via the external source. Users with primary email addresses on the following ISP domains cannot be deactivated: - aol.com - charter.net - comcast.net - duck.com - email.com - gmail.com - hotmail.com - icloud.com - live.com - mail.com - mail.ru - outlook.com - rocketmail.com - usa.com - verizon.net - web.de - yahoo.com ### Downgrade user - [POST /users/{userId}/plans/{planId}/downgrade](https://developers.smartsheet.com/api/smartsheet/openapi/users/downgrade-user.md): Downgrades the user associated with the specified Smartsheet plan. Downgrading a user does not affect their existing permissions on owned or shared items. A user can be downgraded to the following seat types: * GUEST - only external users can be downgraded to this seat type. * VIEWER > Who can use this operation? > > Permissions: System Admin ### Update user profile image - [POST /users/{userId}/profileimage](https://developers.smartsheet.com/api/smartsheet/openapi/users/update-user-profile-image.md): Uploads an image to the user profile. Uploading a profile image differs from Adding an Image to a Cell in the following ways: * A Content-Length header is not required * Allowable file types are limited to: gif, jpg, and png * Maximum file size is determined by the following rules: * If you have not defined a custom size and the image is larger than 1050 x 1050 pixels, Smartsheet scales the image down to 1050 x 1050 * If you have defined a custom size, Smartsheet uses that as the file size max * If the image is not square, Smartsheet uses a solid color to pad the image ### Reactivate user - [POST /users/{userId}/reactivate](https://developers.smartsheet.com/api/smartsheet/openapi/users/reactivate-user.md): Reactivates the user associated with the current Smartsheet plan, restoring the user's access to Smartsheet, owned items, and shared items. Optionally, with Enterprise Plan Manager (EPM) enabled, you can specify the ID of a user within your managed plan hierarchy. > Important: You can reactivate the user only if that user has been deactivated for less than thirty (30) days. > Who can use this operation? > > Permissions: System Admin > > This operation is unavailable for Smartsheet Gov. Attempting to reactivate a user that matches any of the following criteria results in an error: - The user's primary email address belongs to an ISP domain (e.g., gmail.com, yahoo.com, outlook.com). For example, see the common ISP domains listed below. - The user's primary email address is unassociated with the current Smartsheet plan domain(s). - The user is not in the plan's organization. Users with primary email addresses on the following ISP domains cannot be reactivated: - aol.com - charter.net - comcast.net - duck.com - email.com - gmail.com - hotmail.com - icloud.com - live.com - mail.com - mail.ru - outlook.com - rocketmail.com - usa.com - verizon.net - web.de - yahoo.com ### Upgrade user - [POST /users/{userId}/plans/{planId}/upgrade](https://developers.smartsheet.com/api/smartsheet/openapi/users/upgrade-user.md): Upgrades the user associated with the specified Smartsheet plan. A user can be upgraded to the following seat types: * GUEST - only external users can be upgraded to this seat type. * MEMBER > Who can use this operation? > > Permissions: System Admin > Note: Upgrading a user to its current seat type returns 200 OK. ### Remove user from plan - [DELETE /users/{userId}/plans/{planId}](https://developers.smartsheet.com/api/smartsheet/openapi/users/remove-user-from-plan.md): Removes a user's access to all items they were previously shared to within the specified plan. This action can't be reversed. ### List user plans - [GET /users/{userId}/plans](https://developers.smartsheet.com/api/smartsheet/openapi/users/list-user-plans.md): List plans to which the user belongs. > Note: For pagination guidance, refer to Token-based pagination. ## Webhooks Smartsheet webhooks are powerful tools for building custom integrations and automating processes. Instead of constantly polling for changes, with webhooks you can configure your applications to receive real-time notifications when specific Smartsheet events occur.

Webhooks guides

To learn more about Smartsheet webhooks in general, start with these [Webhooks guide](/api/smartsheet/guides/webhooks) articles: - [Webhooks overview](/api/smartsheet/guides/webhooks.md) - [Create an event-handling endpoint](/api/smartsheet/guides/webhooks/create-an-event-handling-endpoint.md) - [Launch a webhook](/api/smartsheet/guides/webhooks/launch-a-webhook.md) - [Webhook callbacks](/api/smartsheet/guides/webhooks/webhook-callbacks.md) - [Webhook verification](/api/smartsheet/guides/webhooks/webhook-verification.md) - [Webhook access](/api/smartsheet/guides/webhooks/webhook-access.md)

Resource-specific guides

To dive into webhooks on a specific resource, check out these guides: - [Sheet webhooks](/api/smartsheet/guides/webhooks.md) - [User / plan-level webhooks](/api/smartsheet/guides/users/automate-user-seat-type-management.md) Continue on to dive into webhook object schemas and operations. ### List webhooks - [GET /webhooks](https://developers.smartsheet.com/api/smartsheet/openapi/webhooks/list-webhooks.md): Gets the list of all webhooks that the user owns (if a user-generated token was used to make the request) or the list of all webhooks associated with the third-party app (if a third-party app made the request). Items in the response are ordered by API cient name > webhook name > creation date. Note: In the response, each webhook's events field defaults to "."], regardless of its actual value. Alternatively, call [GET /webhook/{webhookId} on an individual webhook to get its events value. DEPRECATION - As early as the sunset date specified in this Changelog entry, webhooks will be sorted by creation date (most recent first) instead of name. See the Changelog entry for migration instructions and details. ### Create webhook - [POST /webhooks](https://developers.smartsheet.com/api/smartsheet/openapi/webhooks/createwebhook.md): Creates a new Webhook. > Important: On creation, a webhook is inactive by default. You can activate the webhook by calling the Update webhook operation on it with enabled set to true. Webhook instance limits Each scope object, such as a plan or a sheet, can have a maximum number of associated webhooks. | Object | Maximum webhooks | | :----------- | :-------------------------- | | Plan | 100 | | Sheet | 100k | > Note: If you're creating a plan-level webhook (plan webhook), you can pass custom headers in your webhook requests, which Smartsheet then adds to all requests that the webhook sends to your callback URL. This is useful for including authentication tokens or other information your application needs. To do this, add a customHeaders object to the request body, with each key-value pair representing a header and its value. > > See also: > > - customHeaders body parameter in the Body section below > - Launch a plan-level webhook > - Create a plan event-handling endpoint article ### Get webhook - [GET /webhooks/{webhookId}](https://developers.smartsheet.com/api/smartsheet/openapi/webhooks/getwebhook.md): Gets a matching webhook based on the specified ID. ### Update webhook - [PUT /webhooks/{webhookId}](https://developers.smartsheet.com/api/smartsheet/openapi/webhooks/updatewebhook.md): Updates the matching Webhook. > Important: If you set enabled to true, the behavior and result depend on the webhook's status and may trigger a webhook verification or, in some cases, cause an error. See Webhook status for details. > Note: If you're creating a plan-level webhook (plan webhook), you can pass custom headers in your webhook requests, which Smartsheet then adds to all requests that the webhook sends to your callback URL. This is useful for including authentication tokens or other information your application needs. To do this, add a customHeaders object to the request body, with each key-value pair representing a header and its value. > > See also: > > - customHeaders body parameter in the Body section below > - Launch a plan-level webhook > - Create a plan event-handling endpoint article ### Delete webhook - [DELETE /webhooks/{webhookId}](https://developers.smartsheet.com/api/smartsheet/openapi/webhooks/deletewebhook.md): Permanently deletes the specified webhook. > Important: This operation permanently deletes the webhook. Alternatively, to temporarily disable the webhook, use the Update webhook operation with enabled set to false. ### Reset shared secret - [POST /webhooks/{webhookId}/resetSharedSecret](https://developers.smartsheet.com/api/smartsheet/openapi/webhooks/resetsharedsecret.md): Resets the shared secret for the specified webhook. You can improve security by using this operation to rotate an API client webhooks' shared secrets at periodic intervals. For more information about how a shared secret is used, see the Authenticating callbacks section in Webhook callbacks.