# Add summary fields

Creates one or more summary fields for the specified sheet.

Endpoint: POST /sheets/{sheetId}/summary/fields
Version: 2.0.0
Security: APIToken, OAuth2

## Path parameters:

  - `sheetId` (number, required)
    ID of the sheet being accessed.

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

## Query parameters:

  - `renameIfConflict` (boolean)
    Set to true if you want to override the requirement for unique summary field names. Repeated names will be adjusted by appending "(1)" or similar after the field name.

## Request fields (application/json):

  - `contactOptions` (array)
    Array of ContactOption objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST.

  - `contactOptions.email` (string)
    A parsable email address.

  - `contactOptions.name` (string)
    Can be a user's name, display name, or free text.

  - `format` (string)
    The format descriptor. Only returned if the include query string parameter contains format and this column has a non-default format applied to it.

  - `formula` (string)
    The formula for a cell, if set.

  - `hyperlink` (object)

  - `hyperlink.reportId` (number)
    If non-null, this hyperlink is a link to the report with this ID.

  - `hyperlink.sheetId` (number)
    If non-null, this hyperlink is a link to the sheet with this ID.

  - `hyperlink.sightId` (number)
    If non-null, this hyperlink is a link to the dashboard with this ID.

  - `hyperlink.url` (string)
    When the hyperlink is a URL link, this property contains the URL value. When the hyperlink is a dashboard/report/sheet link (that is, dashboardId, reportId, or sheetId is non-null), this property contains the permalink to the dashboard, report, or sheet.

  - `image` (object)

  - `image.altText` (string)
    Alternate text for the image.

  - `image.height` (number)
    Original height (in pixels) of the uploaded image.

  - `image.id` (string)
    Image ID.

  - `image.width` (number)
    Original width (in pixels) of the uploaded image.

  - `index` (number)
    Field index or position. This number is zero-based.

  - `locked` (boolean)
    Indicates whether the field is locked.

  - `objectValue` (any)

  - `options` (array)
    When applicable for PICKLIST column type. Array of the options available for the field.

  - `symbol` (string)
    When applicable for PICKLIST column type.

  - `title` (string)
    Arbitrary name, must be unique within summary.

  - `type` (string)
    Enum: "ABSTRACT_DATETIME", "CHECKBOX", "CONTACT_LIST", "DATE", "DATETIME", "DURATION", "MULTI_CONTACT_LIST", "MULTI_PICKLIST", "PICKLIST", "PREDECESSOR", "TEXT_NUMBER"

  - `validation` (boolean)
    Indicates whether summary field values are restricted to the type.

## Response 200 fields (application/json):

  - `version` (number,null)
    New version of the sheet. Applicable only for operations which update sheet data.

  - `failedItems` (array,null)
    Array of BulkItemFailure objects which represents the items that failed to be added or updated. See [Bulk operations > Partial success](/api/smartsheet/guides/advanced-topics/scalability-options) for more information. Applicable only for bulk operations that support partial success.

  - `failedItems.rowId` (number,null)
    The ID of the row that failed. Applicable only to bulk row operations.

  - `failedItems.error` (object)
    The error caused by the failed item.

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

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

  - `failedItems.error.message` (string)
    Descriptive error message.

  - `failedItems.index` (number)
    The index of the failed item in the bulk request array.

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

  - `result.id` (number)
    SummaryField ID.

  - `result.contactOptions` (array)
    Array of ContactOption objects to specify a pre-defined list of values for the column. Column type must be CONTACT_LIST.

  - `result.contactOptions.email` (string)
    A parsable email address.

  - `result.contactOptions.name` (string)
    Can be a user's name, display name, or free text.

  - `result.createdAt` (any)

  - `result.createdBy` (object)
    User object containing name and email of the creator of this summary field.

  - `result.createdBy.email` (string)
    Example: "jane.doe@smartsheet.com"

  - `result.createdBy.name` (string)
    Example: "Jane Doe"

  - `result.displayValue` (string)
    Visual representation of cell contents, as presented to the user in the UI.

  - `result.format` (string)
    The format descriptor. Only returned if the include query string parameter contains format and this column has a non-default format applied to it.

  - `result.formula` (string)
    The formula for a cell, if set.

  - `result.hyperlink` (object)

  - `result.hyperlink.reportId` (number)
    If non-null, this hyperlink is a link to the report with this ID.

  - `result.hyperlink.sheetId` (number)
    If non-null, this hyperlink is a link to the sheet with this ID.

  - `result.hyperlink.sightId` (number)
    If non-null, this hyperlink is a link to the dashboard with this ID.

  - `result.hyperlink.url` (string)
    When the hyperlink is a URL link, this property contains the URL value. When the hyperlink is a dashboard/report/sheet link (that is, dashboardId, reportId, or sheetId is non-null), this property contains the permalink to the dashboard, report, or sheet.

  - `result.image` (object)

  - `result.image.altText` (string)
    Alternate text for the image.

  - `result.image.height` (number)
    Original height (in pixels) of the uploaded image.

  - `result.image.id` (string)
    Image ID.

  - `result.image.width` (number)
    Original width (in pixels) of the uploaded image.

  - `result.index` (number)
    Field index or position. This number is zero-based.

  - `result.locked` (boolean)
    Indicates whether the field is locked.

  - `result.lockedForUser` (boolean)
    Indicates whether the field is locked for the requesting user.

  - `result.modifiedAt` (any)

  - `result.modifiedBy` (object)
    User object containing name and email of the user who most recently modified this summary field.

  - `result.objectValue` (any)

  - `result.options` (array)
    When applicable for PICKLIST column type. Array of the options available for the field.

  - `result.symbol` (string)
    When applicable for PICKLIST column type.

  - `result.title` (string)
    Arbitrary name, must be unique within summary.

  - `result.type` (string)
    Enum: "ABSTRACT_DATETIME", "CHECKBOX", "CONTACT_LIST", "DATE", "DATETIME", "DURATION", "MULTI_CONTACT_LIST", "MULTI_PICKLIST", "PICKLIST", "PREDECESSOR", "TEXT_NUMBER"

  - `result.validation` (boolean)
    Indicates whether summary field values are restricted to the type.

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