# Changelog

Here is the log of changes to the API.

> **Note:** To learn the deprecation process, see [Deprecation process](/api/smartsheet/guides/deprecation-process).


## Revised sunset timeline for Browse endpoints

Date: Jan-09-2026

**UPDATE:**

We removed the previously announced sunset date for the Browse-related endpoints (see this [changelog entry](/api/smartsheet/changelog#2025-03-25)). While the endpoints remain deprecated, a final sunset date is currently being re-evaluated. We will provide an updated timeline as soon as it is finalized.

## Update: `POST /users` sets `licensedSheetCreator` to `true` for users added to user model plans

Date: Jan-08-2026

**UPDATE:**

We updated the `User` schema, removing the `licensedSheetCreator` attribute's default.

We updated documentation for the [`POST /users`](/api/smartsheet/openapi/users/add-user) operation to note that adding a user to a user model plan via `POST /users` automatically allocates a seat, enabling the user to create and own sheets. Consequently, the operation sets `licensedSheetCreator` to `true`, regardless of the value provided in the request body.

## Fixed "Move folder" response schema and marked `destinationType` required for moving dashboards/folders/sheets

Date: Dec-23-2025

**FIX:**

- We corrected the response schema for [`POST /folders/{folderId}/move`](/api/smartsheet/openapi/folders/move-folder) (Move folder).
- We correctly indicated that the `destinationType` body attribute is required (not optional) for the "Move dashboard", "Move folder", and "Move sheet" operations:
  - [`POST /sights/{sightId}/move`](/api/smartsheet/openapi/dashboards/move-sight) (Move dashboard)
  - [`POST /folders/{folderId}/move`](/api/smartsheet/openapi/folders/move-folder) (Move folder)
  - [`POST /sheets/{sheetId}/move`](/api/smartsheet/openapi/sheets/move-sheet) (Move sheet)


## Fixed the response specs for the `GET /search` and `GET /search/sheets/{sheetId}` operations

Date: Dec-22-2025

**FIX:**

For [`GET /search`](/api/smartsheet/openapi/search/list-search) (Search everything) calls that include the `include=favoriteFlag` query parameter setting, we now reflect the `favorite` and `parentObjectFavorite` boolean item attributes in the response.

For [`GET /search`](/api/smartsheet/openapi/search/list-search) (Search everything) and [`GET /search/sheets/{sheetId}`](/api/smartsheet/openapi/search/list-search-sheet) (Search sheet), we now distinguish between matching items that do or don't have parent item objects. The [Search result item](/api/smartsheet/openapi/search/searchresultitem) and [Search result sub-item](/api/smartsheet/openapi/search/searchresultsubitem) schemas demonstrate the respective cases.

## Fixed spec for `PATCH /shares/{shareId}`--it doesn't support asset ownership transfer

Date: Dec-18-2025

**FIX:**

We corrected the [`PATCH /shares/{shareId}`](/api/smartsheet/openapi/sharing/update-asset-share) (Update asset share) operation specification by removing `"OWNER"` as a possible value for the [`accessLevel`](/api/smartsheet/openapi/sharing/update-asset-share#sharing/update-asset-share/t=request&path=accesslevel) request body attribute.

The operation doesn't support asset ownership transfer.

## Fix object value specs for sheet summary field and dashboard widget content

Date: Dec-12-2025

**FIX:**

We fixed the `objectValue` attribute specs for **summary fields** and **cell-based dashboard widget content**.

Here are the spec corrections:

- Sheet summary field-related `objectValue` attributes, such as the one for [Summary field](/api/smartsheet/openapi/sheetsummary/summaryfield#path=objectvalue), are corrected to reflect supporting these types:
  - `boolean`
  - `number`
  - `string`
  - [Contact object value](/api/smartsheet/openapi/schemas/contactobjectvalue)
  - [Date object value](/api/smartsheet/openapi/schemas/dateobjectvalue)
> **Note:** Summary field `objectValue` doesn't support `AbstractDatetimeObjectValue`, `DatetimeObjectValue`, `DurationObjectValue`, `MultiContactObjectValue`, `MultiPicklistObjectValue`, or `PredecessorList`.
- [Dashboard widget content cell data](/api/smartsheet/openapi/dashboards/widget#path=contents&oneof=1/celldata) element [`objectValue`](/api/smartsheet/openapi/dashboards/widget#path=contents&oneof=1/celldata/objectvalue) and [`cell.objectValue`](/api/smartsheet/openapi/dashboards/widget#path=contents&oneof=1/celldata/cell/objectvalue) attributes are corrected to reflect supporting these types:
  - `boolean`
  - `number`
  - `string`
  - [Abstract datetime object value](/api/smartsheet/openapi/schemas/abstractdatetimeobjectvalue)
  - [Contact object value](/api/smartsheet/openapi/schemas/contactobjectvalue)
  - [Date object value](/api/smartsheet/openapi/schemas/dateobjectvalue)
  - [Datetime object value](/api/smartsheet/openapi/schemas/datetimeobjectvalue)
  - [Duration object value](/api/smartsheet/openapi/schemas/durationobjectvalue)
  - [Multi-contact object value](/api/smartsheet/openapi/schemas/multicontactobjectvalue)
  - [Multi-picklist object value](/api/smartsheet/openapi/schemas/multipicklistobjectvalue)
  - [Predecessor list object value](/api/smartsheet/openapi/schemas/predecessorlist)
- [Contact object value](/api/smartsheet/openapi/schemas/contactobjectvalue) is corrected to include the following attributes:
  - `emailId`
  - `lookUpName`
  - `userId`
- [Cell](/api/smartsheet/openapi/cells/cell) is corrected to to include the `rowId` attribute.


## Improved the dashboard widget hyperlink spec

Date: Dec-10-2025

**IMPROVEMENT:**

We improved the dashboard [widget hyperlink](/api/smartsheet/openapi/schemas/widgethyperlink) schema specification by defining objects that represent the various types of widget hyperlinks.

## Deprecated the copy-related query parameters for "Create folder" and "Create workspace"

Date: Dec-09-2025

**DEPRECATION:**

**We deprecated the copy-related query parameters for [Create folder](/api/smartsheet/openapi/folders/create-folder-folder) and [Create workspace](/api/smartsheet/openapi/workspaces/create-workspace) endpoints** because the [Copy folder](/api/smartsheet/openapi/folders/copy-folder) and [Copy workspace](/api/smartsheet/openapi/workspaces/copy-workspace) endpoints supersede their functionality.

> **SUNSET DATE:** Mar-09-2026


For [Create folder](/api/smartsheet/openapi/folders/create-folder-folder) (`POST /folders/{folderId}/folders`), we deprecated the following copy-related parameters and will remove them on the sunset date:

- `include`
- `exclude`
- `skipRemap`


For [Create workspace](/api/smartsheet/openapi/workspaces/create-workspace) (`POST /workspaces`), we deprecated the following copy-related parameters and will remove them on the sunset date:

- `include`
- `skipRemap`


**Migration instructions**

In cases where you're using [Create folder](/api/smartsheet/openapi/folders/create-folder-folder) or [Create workspace](/api/smartsheet/openapi/workspaces/create-workspace) to copy a folder or workspace, follow these migration steps:

1. Replace your endpoint path for [Create folder](/api/smartsheet/openapi/folders/create-folder-folder) or [Create workspace](/api/smartsheet/openapi/workspaces/create-workspace) with the `/folders/{folderId}/copy` path for [Copy folder](/api/smartsheet/openapi/folders/copy-folder) or the `/workspaces/{workspaceId}/copy` path for [Copy workspace](/api/smartsheet/openapi/workspaces/copy-workspace), respectively.
2. Set the path parameter to the ID of the folder or workspace you're copying.
3. Add the copy-related query parameter settings as you did previously.
4. Specify the body parameters per the new endpoint.
Body parameter mapping
| Old parameter | New parameter | New parameter description |
|  --- | --- | --- |
| `name` | `newName` | Name of the new folder or workspace |
| (not applicable) | `destinationType` (for **Copy folder** only) | "folder", "workspace", "home" (deprecated) |
| (not applicable) | `destinationId` (for **Copy folder** only) | Destination's unique identifier |
5. Adapt your code to either the [Copy folder](/api/smartsheet/openapi/folders/copy-folder) or [Copy workspace](/api/smartsheet/openapi/workspaces/copy-workspace) endpoint response schema.


## Refined the spec for Workspace and Folder endpoints

Date: Dec-09-2025

For folder and workspace endpoints, we made the following changes:

- **Fixed [Copy workspace](/api/smartsheet/openapi/workspaces/copy-workspace) by removing the destination ID/type request body properties**.
- **Updated schemas and descriptions** for several endpoints.


**FIX:**

For [Copy workspace](/api/smartsheet/openapi/workspaces/copy-workspace) (`POST /workspaces/{workspaceId}`), we removed the following request body properties:

- `destinationId` (formerly required)
- `destinationType`


**UPDATE:**

We corrected and updated schemas and descriptions for these endpoints:

- [Create workspace](/api/smartsheet/openapi/workspaces/create-workspace) (`POST /workspaces`)
- [Update workspace](/api/smartsheet/openapi/workspaces/update-workspace) (`PUT /workspaces/{workspaceId}`)
- [Copy workspace](/api/smartsheet/openapi/workspaces/copy-workspace) (`POST /workspaces/{workspaceId}`)
- [Create folder in workspace](/api/smartsheet/openapi/workspaces/create-workspace-folder) (`POST /workspaces/{workspaceId}/folders`)
- [Create folder in folder](/api/smartsheet/openapi/folders/create-folder-folder) (`POST /folders/{folderId}/folders`)
- [Update folder](/api/smartsheet/openapi/folders/update-folder) (`PUT /folders/{folderId}/folders`)
- [Copy folder](/api/smartsheet/openapi/folders/copy-folder) (`POST /folders/{folderId}`)


## Fix Proof schema

Date: Dec-03-2025

**FIX:**

We fixed the following parts of the [Proof](/api/smartsheet/openapi/proofs/proof) schema:

- Corrected the name of property `proofType` to `type`.
- Added the missing property named `documentType`.


## Deprecated includeAll and offset-based pagination for dashboards

Date: Dec-03-2025

**DEPRECATION:**

For [`GET /sights`](/api/smartsheet/openapi/dashboards/list-sights) (List dashboards), we deprecated the `includeAll` parameter and other query parameters and response properties related to the endpoint's support for unbounded results and offset-based pagination. We are replacing them with [token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination) (now available). These changes reduce latency, mitigate performance issues, and add stability, especially for users with many dashboards.

**SUNSET DATE:** Jun-03-2026

> **Important:** During this deprecation period, the deprecated functionality and components remain available.
**Now is the best time to migrate** to [token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination) for [`GET /sights`](/api/smartsheet/openapi/dashboards/list-sights).


The following query parameters and response properties are deprecated.

- Query parameters:
  - `includeAll`
  - `modifiedSince`
  - `page`
  - `pageSize`
- Response properties:
  - `pageNumber`
  - `pageSize`
  - `totalCount`
  - `totalPages`


## Reset the includeAll pagination sunset date to Jun-03-2026

Date: Dec-01-2025

**DEPRECATION:**

We reset the **sunset date to June 3rd, 2026** for the `includeAll`, pagination-related deprecations listed [here](#2025-08-04).

## Added template support in workspace and folder children endpoints

Date: Nov-20-2025

**FIX:**

We made the `childrenResourceTypes` parameter optional for the [`GET /workspaces/{workspaceId}/children`](/api/smartsheet/openapi/workspaces/get-workspace-children) and [`GET /folders/{folderId}/children`](/api/smartsheet/openapi/folders/get-folder-children) endpoints. When not specified, the endpoints return all child resource types, including templates.

**ADDITION:**

We added support for retrieving templates as child objects in workspace and folder children listings:

- Added `template` as a valid resource type for the [`GET /workspaces/{workspaceId}/children`](/api/smartsheet/openapi/workspaces/get-workspace-children) and [`GET /folders/{folderId}/children`](/api/smartsheet/openapi/folders/get-folder-children) endpoints.
> **Note:** The [`GET /workspaces/{workspaceId}/children`](/api/smartsheet/openapi/workspaces/get-workspace-children) and [`GET /folders/{folderId}/children`](/api/smartsheet/openapi/folders/get-folder-children) endpoints provide an alternative to using the deprecated endpoint **List templates** (`GET /templates`).
- Added `templates` to the `childrenResourceTypes` parameter to retrieve templates. By default, templates are included.
> **Note:** To filter on templates, you must include both `sheets` and `templates` in the `childrenResourceTypes` parameter (for example, `childrenResourceTypes=sheets,templates`), because the templates are sheet templates.


## Added plan-level webhook event filtering

Date: Nov-12-2025

**ADDITION:**

We enhanced plan-level webhooks to include event filtering. You now have granular control over which events trigger a callback for a plan-level webhook.

- **Enhanced create and update endpoints** - The [`POST /webhooks`](/api/smartsheet/openapi/webhooks/createwebhook) and [`PUT /webhooks/{webhookId}`](/api/smartsheet/openapi/webhooks/updatewebhook) endpoints now include filtering capabilities in the request schema, allowing precise control over which events trigger plan-level webhook callbacks.
- **Added a webhook event types catalog** - Documented available webhook events at [webhook event types](/api/smartsheet/webhook-event-types), providing event schemas and usage examples.


## 2025-10-29 Provisional seat expiration surfaced for users

**ADDITION:**

We added a property called `provisionalExpirationDate` to surface the expiration timestamp of a user's provisional seat type (that is, where `"seatType": "PROVISIONAL_MEMBER"`). The timestamp marks the end of the **review period** for which the user is a **Provisional Member**. To learn more about Provisional Membership, see  this article.

The `provisionalExpirationDate` property appears in the following elements:

- Responses from [GET /2.0/users](/api/smartsheet/openapi/users/list-users), when the `planId` query parameter is included
- Responses from [GET /2.0/users/{userId}/plans](/api/smartsheet/openapi/users/list-user-plans)
- [User seat type update](/api/smartsheet/openapi/schemas/user_seattypeupdate_callbackevent) webhook events


## 2025-10-07 Limit request rates for Get folder and Get workspace

**DEPRECATION:**

We've set a 60 requests per minute per API token limit for the following deprecated, unbounded endpoints:

- Get folder (`GET /folders/{folderId}`)
- Get workspace (`GET /workspaces/{workspaceId}`)


## 2025-10-02 User seat type and plan management additions

**ADDITION:**

We've added new operations and improvements to support the following user seat type and plan management scenarios for System Admins:

* **Include seat type in user listings:** Use the `planId` query parameter in a `GET /2.0/users` call to include the following details for each user:
  * **Seat type** relative to the plan
  * **Last seat type change timestamp**
  * **Whether the user is internal to the plan domain**
  * **Whether the user is provisionally licensed**
You can also filter the results by seat type by including the `seatType` query parameter. Valid seat types are: `VIEWER`, `GUEST`, `PROVISIONAL_MEMBER`, and `MEMBER`. See [List users](/api/smartsheet/openapi/users/list-users) for more information.


* **List all of a user's plans:** Call `GET /2.0/users/{userId}/plans` to list all plans a user belongs to.
See [List user plans](/api/smartsheet/openapi/users/list-user-plans) for more information.


* **Remove a user from a plan:** Call `DELETE /2.0/users/{userId}/plans/{planId}` to remove a user's access to all items they were previously shared to within the plan.
See [Remove user from plan](/api/smartsheet/openapi/users/remove-user-from-plan) for more information.
> **Warning:** This action is irreversible.


## 2025-09-03 New plan-level webhooks and user upgrade/downgrade operations

**ADDITION:**

To support automating user seat type management, we added user seat type update events, plan-level webhooks, and user upgrade/downgrade operations.

**Webhooks:**

- **Plan-level webhooks** - You can now subscribe to user seat type updates on your plan. See [Create webhook (POST /webhooks)](/api/smartsheet/openapi/webhooks/createwebhook) for details.
- [User seat type update event](/api/smartsheet/openapi/schemas/user_seattypeupdate_callbackevent) - This schema specifies the plan, user, and the user’s new seat type.


**Operations:**

- [Upgrade user (POST /users/{userId}/plans/{planId}/upgrade)](/api/smartsheet/openapi/users/upgrade-user) - Move a user to a higher permission tier on your plan.
- [Downgrade user (POST /users/{userId}/plans/{planId}/downgrade)](/api/smartsheet/openapi/users/downgrade-user) - Move a user to a lower permission tier on your plan.


**Developer guide:** [Automate user seat type management](/api/smartsheet/guides/users/automate-user-seat-type-management) demonstrates using the new webhooks and operations to automate user seat type management.

## 2025-08-04

**DEPRECATION:**

We’re changing several of our resource retrieval endpoints (ones that list references to resource objects and that fetch individual objects) to improve performance, reduce network latency, and conserve resources. For most of these endpoints, we’re replacing offset-based pagination with [token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination). At the very least, we’re removing the ability of these endpoints to return unbounded results.

Consequently, we [deprecated](/api/smartsheet/guides/deprecation-process) several functionality components, and in most cases, we’ve provided improved components to replace them.

**SUNSET DATE:** Jun-03-2026

> **Important:** During this deprecation period, the deprecated functionality remains in place, and applicable replacement functionality is also available. **Now is the best time to migrate** from the deprecated functionality.


> **Note:** See [Deprecation process](/api/smartsheet/guides/deprecation-process) for deprecation and sunset term definitions, and for details on the deprecation process.


The following sections describe the deprecations (and applicable replacements), in order by simplest migrations first.

### Webhook pagination

We [deprecated](/api/smartsheet/guides/deprecation-process) the following [List webhooks](/api/smartsheet/openapi/webhooks/list-webhooks) (`GET /webhooks`) endpoint functionality to reduce latency, mitigate performance issues, and add stability, especially for users with many webhooks.

- Deprecated the `includeAll` query parameter and will remove it.
- Deprecated the `pageSize` query parameter's unlimited value range and will set the maximum value to 10,000.
- Deprecated the `totalCount` response attribute and will set it to `-1`.
- Deprecated the `totalPages` response attribute and will set it to `-1`.
- Deprecated sorting the returned webhooks by name and will sort them by creation date (most recent first).


If you're currently using the `includeAll` parameter, update your code to page through the results using [offset-based pagination](/api/smartsheet/guides/basics/pagination#offset-based-pagination) via the `pageSize` and `page` parameters.

Otherwise, if you're not currently using the `includeAll` parameter but are using a `pageSize` greater than `10000`, reduce your page size to `10000` or lower.

### Dashboard pagination (deprecation preview)

> **Note:** Token-based pagination for this endpoint is delayed, but is expected within the next few weeks. Please stay tuned for a follow-up changelog entry announcing token-based pagination availability for this endpoint.


We will be [deprecating](/api/smartsheet/guides/deprecation-process) the [List dashboards](/api/smartsheet/openapi/dashboards/list-sights) (`GET /sights`) operation's [offset-based pagination](/api/smartsheet/guides/basics/pagination#offset-based-pagination) and its ability to return an unbounded number of dashboards in a single request. [Token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination) is replacing the offset-based pagination. These planned changes reduce latency, mitigate performance issues, and add stability, especially for users with many dashboards.

The following query parameters and response properties will be deprecated.

- Query parameters:
  - `includeAll`
  - `modifiedSince`
  - `page`
  - `pageSize`
- Response properties:
  - `pageNumber`
  - `pageSize`
  - `totalCount`
  - `totalPages`


### List Workspaces pagination

We [deprecated](/api/smartsheet/guides/deprecation-process) the [List workspaces](/api/smartsheet/openapi/workspaces/list-workspaces) (`GET /workspaces`) operation's [offset-based pagination](/api/smartsheet/guides/basics/pagination#offset-based-pagination) and the operation's ability to return an unbounded list of results in a single request. [Token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination) is replacing the offset-based pagination. These changes will reduce latency, mitigate performance issues, and improve stability, especially for users with many workspaces.

During the deprecation, the operation will continue to support [offset-based pagination](/api/smartsheet/guides/basics/pagination#offset-based-pagination) and will support the new [token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination). That will be the optimal time to migrate to [token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination) using the `paginationType=token` request parameter setting to get your first results page and the `lastKey` request parameter to get each subsequent results page.

The following query parameters and response properties are deprecated.

Deprecated query parameters:

- `includeAll`
- `page`
- `pageSize`


Deprecated response properties:

- `pageNumber`
- `pageSize`
- `totalCount`
- `totalPages`


### Template listing endpoints

We [deprecated](/api/smartsheet/guides/deprecation-process) the following template endpoints.

- List templates (`GET /templates`) - No direct replacement, but alternatives are described below.
- List public templates (`GET /templates/public`) - No replacement.


As an alternative to getting all accessible templates via `GET /templates`, you can use the [`GET /workspaces/{workspaceId}/children`](/api/smartsheet/openapi/workspaces/get-workspace-children) and [`GET /folders/{folderId}/children`](/api/smartsheet/openapi/folders/get-folder-children) endpoints with the `childrenResourceTypes=sheets,templates` parameter, to list templates specific to a workspace or folder.

### Folder and workspace pagination and fetching

We [deprecated](/api/smartsheet/guides/deprecation-process) the following folder and workspace endpoints and are replacing them with new endpoints.

**Deprecated endpoints:**

* List folders (`GET /folders/{folderId}/folders`)
* List workspace folders (`GET /workspaces/{workspaceId}/folders`)
* Get folder (`GET /folders/{folderId}`)
* Get workspace (`GET /workspaces/{workspaceId}`)


**New replacement endpoints:**

* [Get folder metadata](/api/smartsheet/openapi/folders/get-folder-metadata) (`GET /folders/{folderId}/metadata`) - Returns the folder's metadata.
* [List folder children](/api/smartsheet/openapi/folders/get-folder-children) (`GET /folders/{folderId}/children`) - Returns the folder's child items.
* [Get workspace metadata](/api/smartsheet/openapi/workspaces/get-workspace-metadata) (`GET /workspaces/{workspaceId}/metadata`) - Returns the workspace's metadata.
* [List workspace children](/api/smartsheet/openapi/workspaces/get-workspace-children) (`GET /workspaces/{workspaceId}/children`) - Returns the workspace's child items.


> **Note:** The *children endpoints return pages of results via [token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination).


**Replacement Mapping:**

| Deprecated endpoint | Replacement endpoint(s) |
|  --- | --- |
| `GET /folders/{folderId}/folders` | [`GET /folders/{folderId}/children`](/api/smartsheet/openapi/folders/get-folder-children) with `childrenResourceTypes=folders` (default returns all resource types) |
| `GET /workspaces/{workspaceId}/folders` | [`GET /workspaces/{workspaceId}/children`](/api/smartsheet/openapi/workspaces/get-workspace-children) with `childrenResourceTypes=folders` (default returns all resource types) |
| `GET /folders/{folderId}` | Both [`GET /folders/{folderId}/metadata`](/api/smartsheet/openapi/folders/get-folder-metadata) and [`GET /folders/{folderId}/children`](/api/smartsheet/openapi/folders/get-folder-children) |
| `GET /workspaces/{workspaceId}` | Both [`GET /workspaces/{workspaceId}/metadata`](/api/smartsheet/openapi/workspaces/get-workspace-metadata) and [`GET /workspaces/{workspaceId}/children`](/api/smartsheet/openapi/workspaces/get-workspace-children) |


**Unsupported Query Params:**

The replacement endpoints above don't support the following [previously-deprecated](/api/smartsheet/changelog#2025-02-03) `include` query parameter values:

- `distributionLink`
- `sheetVersion` - Alternatively, call [Get sheet version](/api/smartsheet/openapi/sheets/get-sheetversion) (`GET /sheets/{sheetId}/version`) to get a sheet's version.


### Sharing sheets, reports, dashboards, and workspaces

We have [deprecated](/api/smartsheet/guides/deprecation-process) the asset-specific sharing endpoints and will be replacing it with new sharing endpoints to improve scalability and performance of our API.

**Deprecated endpoints:**

* List sheet shares (`GET /sheets/{sheetId}/shares`)
* List report shares (`GET /reports/{reportId}/shares`)
* List dashboard shares (`GET /sights/{sightId}/shares`)
* List workspace shares (`GET /workspaces/{workspaceId}/shares`)
* Get sheet share (`GET /sheets/{sheetId}/shares/{shareId}`)
* Get report share (`GET /reports/{reportId}/shares/{shareId}`)
* Get dashboard share (`GET /sights/{sightId}/shares/{shareId}`)
* Get workspace share (`GET /workspaces/{workspaceId}/shares/{shareId}`)
* Share sheet (`POST /sheets/{sheetId}/shares`)
* Share report (`POST /reports/{reportId}/shares`)
* Share dashboard (`POST /sights/{sightId}/shares`)
* Share workspac (`POST /workspaces/{workspaceId}/shares`)
* Update sheet share (`PUT /sheets/{sheetId}/shares/{shareId}`)
* Update report share (`PUT /reports/{reportId}/shares/{shareId}`)
* Update dashboard share (`PUT /sights/{sightId}/shares/{shareId}`)
* Update workspace share (`PUT /workspaces/{workspaceId}/shares/{shareId}`)
* Delete sheet share (`DELETE /sheets/{sheetId}/shares/{shareId}`)
* Delete report share (`DELETE /reports/{reportId}/shares/{shareId}`)
* Delete dashboard share (`DELETE /sights/{sightId}/shares/{shareId}`)
* Delete workspace share (`DELETE /workspaces/{workspaceId}/shares/{shareId}`)


**New replacement endpoints:**

* [List asset shares](/api/smartsheet/openapi/sharing/list-asset-shares) (`GET /shares`) - Retrieves a list of all users and groups to whom the specified asset is shared, and their access level.
* [Get asset share](/api/smartsheet/openapi/sharing/get-asset-share) (`GET /shares/{shareId}`) - Retrieves a specific share for the specified asset.
* [Share asset](/api/smartsheet/openapi/sharing/share-asset) (`POST /shares`)- Shares an asset with the specified users and/or groups.
* [Update asset share](/api/smartsheet/openapi/sharing/update-asset-share) (`PATCH /shares/{shareId}`)- Updates the share for a specified asset.
* [Delete asset share](/api/smartsheet/openapi/sharing/delete-asset-share) (`DELETE /shares/{shareId}`) - Deletes the share for a specified asset.


**Replacement Mapping:**

| Deprecated endpoint | Replacement endpoint(s) |
|  --- | --- |
| `GET /sheets/{sheetId}/shares` | [`GET /shares`](/api/smartsheet/openapi/sharing/list-asset-shares) |
| `GET /reports/{reportId}/shares` | [`GET /shares`](/api/smartsheet/openapi/sharing/list-asset-shares) |
| `GET /sights/{sightId}/shares` | [`GET /shares`](/api/smartsheet/openapi/sharing/list-asset-shares) |
| `GET /workspaces/{workspaceId}/shares` | [`GET /shares`](/api/smartsheet/openapi/sharing/list-asset-shares) |
| `GET /sheets/{sheetId}/shares/{shareId}` | [`GET /shares/{shareId}`](/api/smartsheet/openapi/sharing/get-asset-share) |
| `GET /reports/{reportId}/shares/{shareId}` | [`GET /shares/{shareId}`](/api/smartsheet/openapi/sharing/get-asset-share) |
| `GET /sights/{sightId}/shares/{shareId}` | [`GET /shares/{shareId}`](/api/smartsheet/openapi/sharing/get-asset-share) |
| `GET /workspaces/{workspaceId}/shares/{shareId}` | [`GET /shares/{shareId}`](/api/smartsheet/openapi/sharing/get-asset-share) |
| `POST /sheets/{sheetId}/shares` | [`POST /shares`](/api/smartsheet/openapi/sharing/share-asset) |
| `POST /reports/{reportId}/shares` | [`POST /shares`](/api/smartsheet/openapi/sharing/share-asset) |
| `POST /sights/{sightId}/shares` | [`POST /shares`](/api/smartsheet/openapi/sharing/share-asset) |
| `POST /workspaces/{workspaceId}/shares` | [`POST /shares`](/api/smartsheet/openapi/sharing/share-asset) |
| `PUT /sheets/{sheetId}/shares/{shareId}` | [`PATCH /shares/{shareId}`](/api/smartsheet/openapi/sharing/update-asset-share) |
| `PUT /reports/{reportId}/shares/{shareId}` | [`PATCH /shares/{shareId}`](/api/smartsheet/openapi/sharing/update-asset-share) |
| `PUT /sights/{sightId}/shares/{shareId}` | [`PATCH /shares/{shareId}`](/api/smartsheet/openapi/sharing/update-asset-share) |
| `PUT /workspaces/{workspaceId}/shares/{shareId}` | [`PATCH /shares/{shareId}`](/api/smartsheet/openapi/sharing/update-asset-share) |
| `DELETE /sheets/{sheetId}/shares/{shareId}` | [`DELETE /shares/{shareId}`](/api/smartsheet/openapi/sharing/delete-asset-share) |
| `DELETE /reports/{reportId}/shares/{shareId}` | [`DELETE /shares/{shareId}`](/api/smartsheet/openapi/sharing/delete-asset-share) |
| `DELETE /sights/{sightId}/shares/{shareId}` | [`DELETE /shares/{shareId}`](/api/smartsheet/openapi/sharing/delete-asset-share) |
| `DELETE /workspaces/{workspaceId}/shares/{shareId}` | [`DELETE /shares/{shareId}`](/api/smartsheet/openapi/sharing/delete-asset-share) |


**Migrating from deprecated sharing endpoints**

We designed all the new endpoints listed above to scale with new asset types that we introduce at Smartsheet. This means that you can use the same endpoint for various asset types, such as sheets, reports, workspaces, and sights (dashboards). For example, the new endpoints support collections and files.

Use the following query parameters to specify the asset type and instance you're working with:

- `assetType` - The type of asset you are working with. One of:
  - `sheet`
  - `report`
  - `workspace`
  - `sight`
  - `collection`
  - `file`
- `assetId` - The ID of the asset you are working with.


Example request: `GET https://api.smartsheet.com/2.0/shares?assetType=sheet&assetId=1234567890`

We're changing the endpoint contracts; specifically the contracts for endpoints that get shares. **As early as the [sunset](/api/smartsheet/guides/deprecation-process) date, we will no longer support offset-based pagination (`page`, `pageSize`, etc) in the Sharing endpoints**. We will have moved exclusively to [token-based pagination](/api/smartsheet/guides/basics/pagination#token-based-pagination). The new endpoints return a `lastKey` response property if there are more shares on the asset; you can use the `lastkey` as a request query parameter to retrieve the next set of results.

Example request: `GET https://api.smartsheet.com/2.0/shares?assetType=sheet&assetId=1234567890&lastKey=abcDefGhIjKlMnOpQrStUvWxYz`

**Request and response schema updates**

The [`Sharing` category](/api/smartsheet/openapi/sharing) lists the new endpoints and object schemas. The endpoint documentation specifies the query parameters and the returned response.

Here are the new object schemas:

- [ShareResponse](/api/smartsheet/openapi/sharing/shareresponse)
- [CreateShareRequest](/api/smartsheet/openapi/sharing/createsharerequest)
- [UpdateShareRequest](/api/smartsheet/openapi/sharing/updatesharerequest)


As early as the [sunset](/api/smartsheet/guides/deprecation-process) date, we will no longer support the `createdAt` and `updatedAt` properties and the `Share` object.

Furthermore, many of the new endpoint response property values are Strings. By using the String type, we can accommodate numeric or alphanumeric values and provide a consistent and predictable API experience. Make sure to update your code to handle these values as Strings.

## 2025-07-31

**ADDITION:**

We added a header named `smartsheet-integration-source` to track the following service request information:

- Integration type
- Smartsheet organization name
- Client integrator name


Example values:

`AI,SampleOrg,My-AI-Connector-v2`

`SCRIPT,SampleOrg2,Accounting-updater-script`

`APPLICATION,SampleOrg3,SheetUpdater`

We added this header to help us distinguish between human-initiated API requests and those coming from third-party services like AI Connectors or ITSM. As AI adoption grows, AI-based connectors are increasingly frequent sources of public API requests. The header enables us to break down requests by their source, which is crucial for the following reasons:

* **Enforce API protective measures**: We can better safeguard our systems by understanding the origin of requests.
* **Enhance services**: We'll gain actionable insights to improve our offerings.
* **Innovate new customer capabilities**: This data will help us build new features using data-driven approaches and sound AI-connector integration analytics.


For more details, see **smartsheet-integration-source** in the [HTTP headers table](/api/smartsheet/guides/basics/http-and-rest#http-headers).

## 2025-07-07

**FIX:**

We removed the `modifiedSince` parameter from the documentation for the [List users](/api/smartsheet/openapi/users/list-users) (`GET /users`) operation because the operation doesn't support a `modifiedSince` parameter.

## 2025-06-25

**IMPROVEMENT:**

We migrated the Event Reporting event type definitions to this site and integrated them into the [OpenAPI document](/api/smartsheet/openapi).

Our new [Event types](/api/smartsheet/event-types) article describes all the event types and links to their schemas and object examples.

## 2025-06-09

**DEPRECATION:**

We deprecated webhook traffic through specific known Smartsheet IP addresses. We’re consolidating all Smartsheet API webhook traffic behind a single DNS: `webhooks.smartsheet.com`. This simplifies firewall management and enhances security. As a result, the origin IP addresses for the webhook verification callbacks sent when enabling a webhook via the [Update Webhook](/api/smartsheet/openapi/webhooks/updatewebhook) (`PUT /webhooks/{webhookId}`) endpoint have changed.

If you have previously allow-listed Smartsheet IP addresses in your firewall for webhook verification or callbacks, you should allow-list traffic from the following domain:


```
webhooks.smartsheet.com
```

Allow-listing the domain ensures successful verification and activation of new webhooks using the [Update Webhook](/api/smartsheet/openapi/webhooks/updatewebhook) endpoint.

> IMPORTANT: Until the sunset date mentioned below, if you previously allow-listed the Smartsheet IP addresses in your firewall, you will continue to to receive existing webhook callbacks.


> NOTE: This change does not affect the process of registering webhooks via the [Create Webhook](/api/smartsheet/openapi/webhooks/createwebhook) (`POST /webhooks`) endpoint or receiving callbacks for webhooks that were enabled prior to this change. Existing Workflow Rules callbacks continue to originate from their current IP addresses until a future migration step. Allow-listing the domain `webhooks.smartsheet.com` is the recommended approach for future compatibility.


**Sunset date:** As early as Sep-01-2025, we will discontinue webhook traffic through the above-mentioned Smartsheet IP addresses.

## 2025-05-15

**SUNSET:**

To improve the performance of the `GET /users/*` endpoint operations, we discontinued the `sheetCount` response attribute behavior for the following endpoint operations:

- [`GET /users`](/api/smartsheet/openapi/users/list-users)
- [`GET /users/me`](/api/smartsheet/openapi/users/get-current-user)
- [`GET /users/{userId}`](/api/smartsheet/openapi/users/get-user)


The `sheetCount` attribute previously indicated the total number of sheets owned by the calling user. Now `sheetCount` consistently returns a value of -1 and is included only if the calling user is active (the [user](/api/smartsheet/openapi/users/user) object's `status` is `ACTIVE`).

Alternatively, you can call [`GET /sheets`](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/list-sheets) to list all the sheets you (or a user you're impersonating) can access. Each [sheet](/api/smartsheet/openapi/sheets/sheet) object listed in the response `data` array shows the user's access level to the sheet. You can filter on sheets with access levels you're interested in for the user. For details on access levels to sheets and other assets, see [Resource access levels](/api/smartsheet/guides/basics/resource-access-levels).

> NOTE: If you're a System Admin, you can impersonate another user to list sheets accessible to that user. For impersonation details, see [User impersonation](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/user-impersonation).


## 2025-05-01

**FIX:**

Corrected the documentation for the [Make Alternate Email Primary](/api/smartsheet/openapi/alternateemailaddress#operation/promote-alternate-email) endpoint `POST /users/{userId}/alternateemails/{alternatEmailId}/makeprimary` to state that it is only for Enterprise plans with the feature activated by Support.

## 2025-04-30

**ADDITION:**

We added the ability to remove users from User Subscription Model (USM) plans via the [`DELETE /users/{userId}`](/api/smartsheet/openapi/users/remove-user) endpoint.

## 2025-04-24

**ADDITION:**

For Event Reporting, we now include the email address of the user responsible for the event. The `emailAddress` property is in each event's `additionalDetails` property.

For example,


```javascript
{
    "eventId": "2.1.saN0P9Eg7CAwauk5yRTz1jS5J6q7Fj9OzJJkJJvgtUI",
    "objectType": "SHEET",
    "action": "LOAD",
    "objectId": 2242242917230468,
    "eventTimestamp": "2025-02-04T22:07:39Z",
    "userId": 4159154089682820,
    "requestUserId": 4159154089682820,
    "source": "API_INTEGRATED_APP",
    "additionalDetails": {
        "emailAddress": "john.doe@company.com"
    }
}
```

> NOTE: For event types that already have an `additionalDetails.emailAddress` property, we preserved their existing email address behavior.


Please see the [Events](/api/smartsheet/openapi/events) section for event endpoints and the [Event types](/api/smartsheet/event-types) reference article.

## 2025-04-22

**DEPRECATION:**

To improve the performance of the `GET /users/*` endpoints, we deprecated the `sheetCount` response attribute for the following endpoint operations:

- [`GET /users`](/api/smartsheet/openapi/users/list-users)
- [`GET /users/me`](/api/smartsheet/openapi/users/get-current-user)
- [`GET /users/{userId}`](/api/smartsheet/openapi/users/get-user)


Sunset date: May-12-2025

As early as the above sunset date, the current `sheetCount` behavior will be discontinued, and `sheetCount` will instead hold the value `-1` and be included only if the user's `status` is `ACTIVE`.

## 2025-04-21

**FIX:**

We fixed the `transferTo` query parameter type of [`DELETE /users/{userId}`](/api/smartsheet/openapi/users/remove-user) from `number` to `integer`, with `format: int64`.

## 2025-04-16

**FIX:**

We fixed the [`DELETE /users/{userId}`](/api/smartsheet/openapi/users/remove-user) specification to reflect that the endpoint takes the following parameters as query parameters--not body parameters:

- `removeFromSharing`
- `transferSheets`
- `transferTo`


## 2025-04-07

**FIX:**

We removed the [Search result item](/api/smartsheet/openapi/search/searchresultitem) schema's `proofUrl` property and mention a proof URL as a possible `contextData` property item. The Search endpoint responses never included a `proofUrl` property--a proof URL was always a possible string value in the context data.

## 2025-04-01

**IMPROVEMENT:**

With the User Subscription Model (USM), you can now [deactivate](/api/smartsheet/openapi/users/deactivate-user) and [reactivate](/api/smartsheet/openapi/users/reactivate-user) users with non-ISP domain primary email addresses belonging to your plan.

Regarding user reactivation, you can now [reactivate](/api/smartsheet/openapi/users/reactivate-user) a user to your plan if the user has been deactivated less than 30 days. The previous threshold was 7 days.

## 2025-03-31

**SUNSET:**

We removed the following properties from `GET /sights/{sightId}` response.

- `favorite` has been deprecated since July 2024.
- `workspace.accessLevel` has never been included in the response.
- `workspace.permalink` has never been included in the response.


## 2025-03-25

**DEPRECATION:**

We deprecated the "Sheets" folder and are replacing it with workspaces for a more streamlined experience.

**Sunset date:** To be determined

We're removing the following endpoints:

- `GET /home`
- `GET /home/folders`
- `GET /folders/personal`
- `POST /sheets`
- `POST /sheets/import`
- `POST /home/folders`


As part of this deprecation, we deprecated the `home` destination type value in all folder-related and sheets-related endpoints.

Learn how to update your code to these changes at [Migrate from using the Sheets folder](/api/smartsheet/guides/updating-code/migrate-from-using-the-sheets-folder).

## 2025-03-14

**FIX:**

We updated the [`Event`](/api/smartsheet/openapi/events/event) schema documentation to provide more accurate examples and comprehensive information:

- Updated the `eventId` example to match the actual format used in production
- Expanded the `objectType` enum to include all possible resource types
- Fixed the property name from `eventTimeStamp` to `eventTimestamp`
- Updated the `source` field description and added the complete list of possible values


## 2025-03-11

**FIX:**

We fixed the `Criteria` schema's `operator` property to include the enum value `IS_ONE_OF`. The value has been part of the schema implementation and is listed in the example but missing from the property documentation.

## 2025-03-07

**FIX:**

We fixed the `Assume-User` header description. The header allows System Administrators (admins) to impersonate or act on behalf of **any** user (including other admins) in their plan to make API calls. For details, see [User Impersonation](/api/smartsheet/guides/advanced-topics/user-impersonation).

## 2025-03-04

**ADDITION:**

We added the POST filteredEvents endpoint. This endpoint allows non-admin users to retrieve events for sheets and workspaces that they have access to.

## 2025-03-03

**DEPRECATION REVERT:**

We reverted deprecation notices for the following endpoint methods:

- [`GET /folders/{folderId}`](/api/smartsheet/openapi/folders/get-folder)
- [`GET /workspaces`](/api/smartsheet/openapi/workspaces/list-workspaces)
- [`GET /workspaces/{workspaceId}`](/api/smartsheet/openapi/workspaces/get-workspace)


See [2025-02-01](#2025-02-01) for the original change.

**ADDITION REVERT:**

We removed the 'lastKey' query parameter from the [`GET /workspaces`](/api/smartsheet/openapi/workspaces/list-workspaces) endpoint method.

See [2025-02-18](#2025-02-18) for the original change.

## 2025-02-18

**ADDITION:**

We added the `lastKey` query parameter and response property for the [`GET /workspaces`](/api/smartsheet/openapi/workspaces/list-workspaces) endpoint method. This is the new and recommended way to get paginated workspace results. The `pageSize` query parameter is used in conjunction with `lastKey`--the `page` and `includeAll` query parameters remain deprecated and will be removed.

## 2025-02-12

**SUNSET:**

We removed the `permalink` option from the `include` query parameter for the following endpoint methods because the option has never been supported:

- [`GET /folders/{folderId}`](/api/smartsheet/openapi/folders/get-folder)
- [`GET /folders/personal`](/api/smartsheet/openapi/home/list-home-contents)


## 2025-02-10

**FIX:**

We corrected response schemas for the following endpoint methods:

- [`GET /folders/{folderId}`](/api/smartsheet/openapi/folders/get-folder)
- [`GET /workspaces/{workspaceId}`](/api/smartsheet/openapi/workspaces/get-workspace)


## 2025-02-03

**DEPRECATION:**

We deprecated the `distributionLink` and `sheetVersion` options for the `include` query parameter on the following endpoint methods:

- [`GET /folders/{folderId}`](/api/smartsheet/openapi/folders/get-folder)
- [`GET /workspaces/{workspaceId}`](/api/smartsheet/openapi/workspaces/get-workspace)


The corresponding response properties will soon stop providing meaningful values.

**DEPRECATION:**

We deprecated the `loadAll` query parameter on the [`GET /folders/{folderId}`](/api/smartsheet/openapi/folders/get-folder) endpoint method, and we will eventually remove it. To replace the `loadAll` query parameter, use calls to [`GET /folders/{folderId}`](/api/smartsheet/openapi/folders/get-folder) to build out workspace structures.

**FIX:**

Regarding the `ownerInfo` option for the `include` query parameter, we clarified which user is returned when
no user is an Owner of the asset.

## 2025-02-01

**DEPRECATION:**

We deprecated the `includeAll` and `page` params for the following endpoint methods:

- [`GET /folders/{folderId}/folders`](/api/smartsheet/openapi/folders/list-folders)
- [`GET /workspaces`](/api/smartsheet/openapi/workspaces/list-workspaces)
- [`GET /workspaces/{workspaceId}/folders`](/api/smartsheet/openapi/workspaces/get-workspace-folders)


We deprecated the following response properties because they are irrelevant to the new pagination system.

- `pageNumber`
- `totalCount`
- `totalPages`


## 2025-01-22

**IMPROVEMENT:**

We now automatically deactivate Webhooks on sheets exceeding any scale limits.

Scale limits:

* 20,000 rows
* 400 columns
* 500,000 cells


Related resources:

* [Webhook Status](/api/smartsheet/openapi/webhooks) has a new related status
* [Webhook Error Codes](/api/smartsheet/openapi/webhooks) has new related error codes


To keep webhooks enabled on a sheet, stay below the limits mentioned above.

As a sheet Owner, you can re-enable webhooks on a sheet by following these steps:

1. Reduce the sheet size to within the limits mentioned above.
2. Execute the [`PUT /webhooks/{webhookId}`](/api/smartsheet/openapi/webhooks/updatewebhook) method with the `enabled` body attribute set to `true`.


Related resources:

* [Webhook Status](/api/smartsheet/openapi/webhooks) has a new related status.
* [Webhook Error Codes](/api/smartsheet/openapi/webhooks) has new related error codes.


## 2024-10-14

**IMPROVEMENT:**

For Smartsheet US and Smartsheet Regions Europe, we introduced a one-minute debounce to optimize event trigger handling in the [Webhooks event callback API](/api/smartsheet/openapi/webhooks). It reduces traffic and prevents workflows from acting on incomplete or transitional data.

## 2024-10-09

**FIX:**

We updated the [`WebContentWidgetContent.type`](/api/smartsheet/openapi/schemas/webcontentwidgetcontent) enum, from `WEBCONTENT` to `WidgetWebContent`. The former enum `WEBCONTENT` was incorrect.