# Create report

Creates a new report from scratch in the specified destination, using the provided scope, columns and report definition.

Endpoint: POST /reports
Version: 2.0.0
Security: 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"

## Request fields (application/json):

  - `name` (string, required)
    Report name.
    Example: "Report name"

  - `columns` (array, required)
    List of columns to be included in the report.

Matching Columns:

The source sheet columns are matched in these ways:

- [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: All indexes of the columns must be unique.

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.

Note: For row reports, exactly one column must have primary=true and it matches to the primary column of each source sheet.

Note: For summary reports, exactly one of the columns must have a sheetNameColumn=true.
    Example: [{"title":"Primary column","type":"TEXT_NUMBER","primary":true,"index":0},{"title":"Sheet name","type":"TEXT_NUMBER","sheetNameColumn":true,"index":1},{"title":"Created at","type":"DATETIME","systemColumnType":"CREATED_DATE","index":2},{"title":"Selected item","type":"PICKLIST","index":3}]

  - `scope` (array, required)
    An array of objects representing sheets and/or workspaces for adding source sheets to the report.
    Example: [{"assetType":"sheet","assetId":1234}]

  - `scope.assetType` (string, required)
    The asset's type.
    Enum: "sheet", "workspace"

  - `scope.assetId` (integer, required)
    The ID of the asset according to its assetType.

  - `reportDefinition` (object)
    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.
    Example: {"filters":{"operator":"AND","criteria":[{"column":{"title":"Primary Column","type":"TEXT_NUMBER","primary":true},"operator":"EQUAL","values":["Test"]}]},"groupingCriteria":[{"column":{"title":"Primary Column","type":"TEXT_NUMBER","primary":true},"sortingDirection":"ASCENDING","isExpanded":true}],"summarizingCriteria":[{"column":{"title":"Primary Column","type":"TEXT_NUMBER","primary":true},"aggregationType":"COUNT"}],"sortingCriteria":[{"column":{"title":"Primary Column","type":"TEXT_NUMBER","primary":true},"sortingDirection":"ASCENDING"}]}

  - `reportDefinition.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)

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

  - `reportDefinition.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.

  - `reportDefinition.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.

  - `reportDefinition.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.

  - `reportDefinition.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"

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

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

  - `reportDefinition.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.

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

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

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

  - `reportDefinition.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.

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

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

  - `reportDefinition.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.

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

  - `isSummaryReport` (boolean)
    It is true if the report is a sheet summary; otherwise it is a row report.

  - `destination` (object, required)

  - `destination.destinationId` (number, required)
    The ID of the destination container.

  - `destination.destinationType` (string, required)
    Type of destination container.
    Enum: "folder", "workspace"

## 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

  - `result` (object)

  - `result.id` (number)
    The report's unique identifier.
    Example: 987654321

  - `result.name` (string)
    The report's name.
    Example: "Q2 Earnings"

  - `result.accessLevel` (string)
    Enum: "ADMIN", "COMMENTER", "EDITOR", "EDITOR_SHARE", "OWNER", "VIEWER"

  - `result.permalink` (string)
    URL to the report in Smartsheet.
    Example: "https://app.smartsheet.com/reports/c8gJxw87cXpRCvCC5PPw6jFhFRrf5r8PxCrxvW21"

  - `result.isSummaryReport` (boolean)
    It is true if the report is a sheet summary; otherwise it is a row report.

  - `result.columns` (array)

## 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.


## Response 400 fields

## Response 403 fields