---
title: "Create cross-sheet references"
method: POST
path: "/sheets/{sheetId}/crosssheetreferences"
tags: ["crossSheetReferences"]
---

# Create cross-sheet references

`POST /sheets/{sheetId}/crosssheetreferences`

Adds a cross-sheet reference between two sheets and defines the data range for formulas. Each distinct data range requires a new cross-sheet reference.

## Headers

- `Content-Type` string

## Request body

- union
  - CrossSheetReferenceRequestWithColumnIds — CrossSheetReference object to create which will refer to the entire columns in the range from startColumnId to endColumnId.
    - `sourceSheetId` number — Sheet ID of source sheet.
    - `name` string — Friendly name of reference. Auto-generated unless specified in Create Cross-sheet References.
    - `endColumnId` number — Defines ending edge of range when specifying one or more columns. Must be used with startColumnId.
    - `startColumnId` number — Defines beginning edge of range when specifying one or more columns. Must be used with endColumnId.
  - CrossSheetReferenceRequestWithRowIds — CrossSheetReference object to create which will refer to the entire rows in the range from startRowId to endRowId.
    - `sourceSheetId` number — Sheet ID of source sheet.
    - `name` string — Friendly name of reference. Auto-generated unless specified in Create Cross-sheet References.
    - `endRowId` number — Defines ending edge of range when specifying one or more rows. Must be used with startRowId.
    - `startRowId` number — Defines beginning edge of range when specifying one or more rows. Must be used with endRowId.
  - CrossSheetReferenceRequestWithColumnAndRowIds — CrossSheetReference object to create with specified cell range.
    - `sourceSheetId` number — Sheet ID of source sheet.
    - `name` string — Friendly name of reference. Auto-generated unless specified in Create Cross-sheet References.
    - `endColumnId` number — Defines ending edge of range when specifying one or more columns. Must be used with startColumnId. To specify an entire column, omit the startRowId and endRowId parameters.
    - `endRowId` number — Defines ending edge of range when specifying one or more rows. Must be used with startRowId. To specify an entire row, omit the startColumnId and endColumnId parameters.
    - `startColumnId` number — Defines beginning edge of range when specifying one or more columns. Must be used with endColumnId. To specify an entire column, omit the startRowId and endRowId parameters.
    - `startRowId` number — Defines beginning edge of range when specifying one or more rows. Must be used with endRowId. To specify an entire row, omit the startColumnId and endColumnId parameters.

## Response `200`

Result object containing a CrossSheetReference object, corresponding to what was specified in the request.

- object
  - `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
  - `failedItems` BulkItemFailure[], nullable — 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.
    - `rowId` number, nullable — The ID of the row that failed. Applicable only to bulk row operations.
    - `error` Error — The error caused by the failed item.
      - `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.
    - `index` number — The index of the failed item in the bulk request array.
  - `version` number, nullable — New version of the sheet. Applicable only for operations which update sheet data.
  - `result` CrossSheetReference
    - `endColumnId` number — Defines ending edge of range when specifying one or more columns. To specify an entire column, omit the startRowId and endRowId parameters.
    - `endRowId` number — Defines ending edge of range when specifying one or more rows. To specify an entire row, omit the startColumnId and endColumnId parameters.
    - `id` number — Cross-sheet reference ID, guaranteed unique within referencing sheet.
    - `name` string — Friendly name of reference. Auto-generated unless specified in Create Cross-sheet References.
    - `startColumnId` number — Defines beginning edge of range when specifying one or more columns. To specify an entire column, omit the startRowId and endRowId parameters.
    - `startRowId` number — Defines beginning edge of range when specifying one or more rows. To specify an entire row, omit the startColumnId and endColumnId parameters.
    - `status` 'BLOCKED' | 'BROKEN' | 'CIRCULAR' | 'DISABLED' | 'INVALID/UNKNOWN' | 'NOT-SHARED' | 'OK' — Status of request: * 'BLOCKED' - A reference is downstream of a circular issue. * 'BROKEN' - The data source location (column, row or sheet) was deleted. * 'CIRCULAR' - The formula reference is self referencing and cannot be resolved. * 'DISABLED' - Updating the reference is temporarily disabled due to maintenance. * 'INVALID/UNKNOWN' - The reference is new and had not been validated. * 'NOT_SHARED' - No common shared users. * 'OK' - The reference is in a good state.
    - `sourceSheetId` number — Sheet ID of source sheet.

## Other responses

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