# Update report definition

Create or entirely replace the definition for the specified report.

Endpoint: PUT /reports/{reportId}/definition
Version: 2.0.0
Security: APIToken, OAuth2

## Header parameters:

  - `Authorization` (string)
    API Access Token used to authenticate requests to Smartsheet APIs.

  - `smartsheet-integration-source` (string)
    Uses the following metadata to distinguish between human-initiated API requests and third-party service-initiated calls by AI Connectors or ITSM:

- Integration source type
- Organization name
- Integration source name 

Format:


TYPE,OrgName,SourceName


Examples: 

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater
    Example: "AI,SampleOrg,My-AI-Connector-v2"

## Path parameters:

  - `reportId` (number, required)
    ID of the report being accessed.

## Request fields (application/json):

  - `filters` (object)
    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)

  - `filters.operator` (string, required)
    The boolean operator to apply to the list of criteria and nestedCriteria.
    Enum: "AND", "OR"

  - `filters.nestedCriteria` (array)
    A recursive list of report filter expressions. Each item is joined to the filter expression with the AND/OR operator defined on this level.

  - `filters.criteria` (array)
    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.

  - `filters.criteria.column` (object, 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.

  - `filters.criteria.operator` (string, required)
    Condition operator.
    Enum: "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"

  - `filters.criteria.values` (array)
    List of filter values.

  - `groupingCriteria` (array)
    List of report grouping criteria.
    Example: [{"column":{"title":"Primary Column","type":"TEXT_NUMBER","primary":true},"sortingDirection":"ASCENDING","isExpanded":true}]

  - `groupingCriteria.column` (object, 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.

  - `groupingCriteria.sortingDirection` (string, required)
    Sorting direction within the group.
    Enum: "ASCENDING", "DESCENDING"

  - `groupingCriteria.isExpanded` (boolean)
    Indicates whether the group is expanded in the UI.

  - `summarizingCriteria` (array)
    List of report summarizing criteria.
    Example: [{"column":{"title":"Primary Column","type":"TEXT_NUMBER","primary":true},"aggregationType":"COUNT"}]

  - `summarizingCriteria.column` (object, 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.

  - `summarizingCriteria.aggregationType` (string, required)
    Type of aggregation.
    Enum: "SUM", "AVG", "MIN", "MAX", "COUNT", "FIRST", "LAST"

  - `sortingCriteria` (array)
    List of report sorting criteria.
    Example: [{"column":{"title":"Primary Column","type":"TEXT_NUMBER","primary":true},"sortingDirection":"ASCENDING"}]

  - `sortingCriteria.column` (object, 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.

  - `sortingCriteria.sortingDirection` (string, required)
    Sorting direction.
    Enum: "ASCENDING", "DESCENDING"

## Response 200 fields (application/json):

  - `message` (string)
    Message that indicates the outcome of the request. (One of SUCCESS or PARTIAL_SUCCESS.)
    Enum: "PARTIAL_SUCCESS", "SUCCESS"

  - `resultCode` (number)
    * '0' Success
* '3' Partial Success of Bulk Operation
    Enum: 0, 3

## Response 400 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 403 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response 404 fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.

## Response default fields (application/json):

  - `refId` (string)
    The ID of the specific error occurrence. Please include this information when contacting Smartsheet support.

  - `errorCode` (number)
    Custom error code from Smartsheet. See the complete [Error Code List](/api/smartsheet/error-codes).

  - `message` (string)
    Descriptive error message.