--- title: "Update report definition" method: PUT path: "/reports/{reportId}/definition" tags: ["reports"] --- # Update report definition `PUT /reports/{reportId}/definition` Create or entirely replace the definition for the specified report. ## Request body - ReportDefinition — The report definition contains `filters`, `grouping` and `sorting` properties of the report. **Note:** When groupingCriteria is defined the primary column of the report will move to the index 0 when it is first rendered by the app. - `filters` ReportFilterExpression — An expression to filter on report columns. It is a recursive object that allows at most three levels. It must include `operator` and at least one of the following: `criteria` or `nestedCriteria` Here is a two-level example: ```json { "operator": "OR", "nestedCriteria": [ { "operator": "AND", "criteria": [ { "column": { "title": "Price", "type": "TEXT_NUMBER" }, "operator": "GREATER_THAN", "values": ["11"] }, { "column": { "primary": true }, "operator": "CONTAINS", "values": ["PROJ-1"] } ] }, { "operator": "AND", "criteria": [ { "column": { "title": "Quantity", "type": "TEXT_NUMBER" }, "operator": "LESS_THAN", "values": ["12"] }, { "column": { "title": "Sold Out", "type": "CHECKBOX" }, "operator": "IS_CHECKED" } ] } ] } ``` It's equivalent to the following pseudo logic: ``` ("Price" > 11 AND "Primary" CONTAINS "PROJ-1") OR ("Quantity" < 12 AND "Sold Out" IS_CHECKED) ``` - `operator` 'AND' | 'OR', required — The boolean operator to apply to the list of `criteria` and `nestedCriteria`. - `nestedCriteria` ReportFilterExpression[] — A recursive list of report filter expressions. Each item is joined to the filter expression with the AND/OR operator defined on this level. - `criteria` object[] — Criteria objects specifying custom criteria against which to match cell values. Each item is joined to the filter expression with the AND/OR operator defined on this level. - `column` union, required — An object for matching a source sheet column for a report. It requires one of: - [`type`, `title`] for **regular columns** - [`type`, `systemColumnType`] for **system columns** - [`type=TEXT_NUMBER`, `primary=true`] for the **primary column** - [`type=TEXT_NUMBER`, `sheetNameColumn=true`] for the special **sheet name report column** **Note:** You can combine multiple `CHECKBOX` columns or multiple `PICKLIST` columns from different sheets into a single report column, even if their underlying symbols differ. However, you can't combine a `CHECKBOX` column with a `PICKLIST` column, because they're different types. **Note:** The system column type `AUTO_NUMBER` is matched together with columns having the same `title` and `type=TEXT_NUMBER`. Therefore, `title` is a required property in this case. - object - `title` string, required — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER', required — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean, required — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean, required — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - `operator` 'EQUAL' | 'NOT_EQUAL' | 'GREATER_THAN' | 'LESS_THAN' | 'CONTAINS' | 'BETWEEN' | 'TODAY' | 'PAST' | 'FUTURE' | 'LAST_N_DAYS' | 'NEXT_N_DAYS' | 'IS_BLANK' | 'IS_NOT_BLANK' | 'IS_NUMBER' | 'IS_NOT_NUMBER' | 'IS_DATE' | 'IS_NOT_DATE' | 'IS_CHECKED' | 'IS_UNCHECKED' | 'IS_ONE_OF' | 'IS_NOT_ONE_OF' | 'LESS_THAN_OR_EQUAL' | 'GREATER_THAN_OR_EQUAL' | 'DOES_NOT_CONTAIN' | 'NOT_BETWEEN' | 'NOT_TODAY' | 'NOT_PAST' | 'NOT_FUTURE' | 'NOT_LAST_N_DAYS' | 'NOT_NEXT_N_DAYS' | 'HAS_ANY_OF' | 'HAS_NONE_OF' | 'HAS_ALL_OF' | 'NOT_ALL_OF' | 'MULTI_IS_EQUAL' | 'MULTI_IS_NOT_EQUAL', required — Condition operator. - `values` union[] — List of filter values. - union - string, nullable - number - DateObjectValue — Object representing a date - `objectType` 'DATE' - `value` string, date — Date in the **full-date** format defined by RFC 3339, section 5.6 - CurrentUserObjectValue — Object representing the current user filter - `objectType` 'CURRENT_USER', required - `groupingCriteria` ReportGroupingCriterion[] — List of report grouping criteria. - `column` union, required — An object for matching a source sheet column for a report. It requires one of: - [`type`, `title`] for **regular columns** - [`type`, `systemColumnType`] for **system columns** - [`type=TEXT_NUMBER`, `primary=true`] for the **primary column** - [`type=TEXT_NUMBER`, `sheetNameColumn=true`] for the special **sheet name report column** **Note:** You can combine multiple `CHECKBOX` columns or multiple `PICKLIST` columns from different sheets into a single report column, even if their underlying symbols differ. However, you can't combine a `CHECKBOX` column with a `PICKLIST` column, because they're different types. **Note:** The system column type `AUTO_NUMBER` is matched together with columns having the same `title` and `type=TEXT_NUMBER`. Therefore, `title` is a required property in this case. - object - `title` string, required — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER', required — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean, required — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean, required — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - `sortingDirection` 'ASCENDING' | 'DESCENDING', required — Sorting direction within the group. - `isExpanded` boolean — Indicates whether the group is expanded in the UI. - `summarizingCriteria` ReportSummarizingCriterion[] — List of report summarizing criteria. - `column` union, required — An object for matching a source sheet column for a report. It requires one of: - [`type`, `title`] for **regular columns** - [`type`, `systemColumnType`] for **system columns** - [`type=TEXT_NUMBER`, `primary=true`] for the **primary column** - [`type=TEXT_NUMBER`, `sheetNameColumn=true`] for the special **sheet name report column** **Note:** You can combine multiple `CHECKBOX` columns or multiple `PICKLIST` columns from different sheets into a single report column, even if their underlying symbols differ. However, you can't combine a `CHECKBOX` column with a `PICKLIST` column, because they're different types. **Note:** The system column type `AUTO_NUMBER` is matched together with columns having the same `title` and `type=TEXT_NUMBER`. Therefore, `title` is a required property in this case. - object - `title` string, required — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER', required — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean, required — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean, required — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - `aggregationType` 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'COUNT' | 'FIRST' | 'LAST', required — Type of aggregation. - `sortingCriteria` ReportSortingCriterion[] — List of report sorting criteria. - `column` union, required — An object for matching a source sheet column for a report. It requires one of: - [`type`, `title`] for **regular columns** - [`type`, `systemColumnType`] for **system columns** - [`type=TEXT_NUMBER`, `primary=true`] for the **primary column** - [`type=TEXT_NUMBER`, `sheetNameColumn=true`] for the special **sheet name report column** **Note:** You can combine multiple `CHECKBOX` columns or multiple `PICKLIST` columns from different sheets into a single report column, even if their underlying symbols differ. However, you can't combine a `CHECKBOX` column with a `PICKLIST` column, because they're different types. **Note:** The system column type `AUTO_NUMBER` is matched together with columns having the same `title` and `type=TEXT_NUMBER`. Therefore, `title` is a required property in this case. - object - `title` string, required — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER', required — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean, required — Set this to `true` to match the primary column. - object - `title` string — Title of a column to match. **Note:** If you specified `primary=true` to match primary columns, you can set the resulting report column title to this value. - `type` 'CHECKBOX' | 'DATE' | 'DATETIME' | 'DURATION' | 'CONTACT_LIST' | 'MULTI_CONTACT_LIST' | 'PICKLIST' | 'MULTI_PICKLIST' | 'PREDECESSOR' | 'TEXT_NUMBER', required — Type of column to match. See [Column Types](/api/smartsheet/openapi/columns). - `systemColumnType` 'CREATED_BY' | 'CREATED_DATE' | 'MODIFIED_BY' | 'MODIFIED_DATE' | 'AUTO_NUMBER' — System column type to match. See [System Columns](/api/smartsheet/openapi/columns). - `sheetNameColumn` boolean, required — Set this to `true` to match the special "Sheet Name" report column. - `primary` boolean — Set this to `true` to match the primary column. - `sortingDirection` 'ASCENDING' | 'DESCENDING', required — Sorting direction. ## Response `200` The operation's success level. - GenericResult - `message` 'PARTIAL_SUCCESS' | 'SUCCESS' — Message that indicates the outcome of the request. (One of `SUCCESS` or `PARTIAL_SUCCESS`.) - `resultCode` 0 | 3 — * '0' Success * '3' Partial Success of Bulk Operation ## Other responses - `400` — This can be caused by the following situations: - The filters contain more than 3 levels of filter expressions. Example response: ```json { "errorCode": 1008, "message": "Unable to parse request. The following error occurred: More than 3 levels of filter expressions defined.", "refId": "abcd1234" } ``` - A column that is not part of the report was referenced in summarizing or sorting criteria. Example response: ```json { "errorCode": 1374, "message": "Unknown column with type TEXT_NUMBER and system column type SHEET_NAME referenced in aggregation or sorting criteria.", "refId": "abcd1234" } ``` - `403` — This can be caused by the following situations: - Caller does not have `EDITOR` or `ADMIN` permissions to the report. ```json { "errorCode": 1004, "message": "You are not authorized to perform this action.", "refId": "abcd1234" } ``` - `404` — This can be caused by the following situations: - Report does not exist. ```json { "errorCode": 1006, "message": "Not Found.", "refId": "abcd1234" } ``` - `default` — Generic error payload. --- [API](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference.md) · [All operations](https://skmtc.net/smartsheet/apis/smartsheet-openapi-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smartsheet/smartsheet-openapi-reference/versions/b4afda95fb51/schema)