# Share asset

Shares an asset with the specified users and/or groups.

One (and only one) of the following is required (alongside accessLevel):
  - email
  - groupId

Endpoint: POST /shares
Version: 2.0.0
Security: APIToken, OAuth2

## Header parameters:

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

## Query parameters:

  - `assetType` (string, required)
    The type of the asset. Used in combination with assetId to determine the asset.
    Enum: "sheet", "report", "sight", "workspace", "collection", "file"

  - `assetId` (string, required)
    The ID of the asset being accessed. It's used in combination with assetType to determine the asset.

Depending on the asset, this may be a numeric or string value.
    Example: "1234567890"

  - `sendEmail` (boolean)
    Either true or false to indicate whether to notify the user by email. Default is false. If true, limit is 1000 emails.

## Request fields (application/json):

  - `email` (string)
    The primary email address of a user to share to. Must be provided if groupId is not provided.
    Example: "test.email@smartsheet.com"

  - `groupId` (number)
    The ID of the group to share to. Must be provided if email is not provided.
    Example: 1234567890

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

  - `subject` (string)
    The subject of the email that is optionally sent to notify the recipient.

Must set the sendEmail query parameter to true for this parameter to take effect.

  - `message` (string)
    The message included in the body of the email that is optionally sent to the recipient.

Must set the sendEmail query parameter to true for this parameter to take effect.

  - `ccMe` (boolean)
    Indicates whether to send a copy of the email to the sharer of the sheet.

Must set the sendEmail query parameter to true for this parameter to take effect.

## Response 200 fields (application/json):

  - `message` (string)
    Message that indicates the request was successful.
    Enum: "SUCCESS"

  - `resultCode` (number)
    * '0' Success
    Enum: 0

  - `result` (array)

  - `result.id` (string, required)
    The ID of the share.
    Example: "AAAMCmYGFOeE"

  - `result.email` (string)
    User's primary email address for user shares.
    Example: "test.email@smartsheet.com"

  - `result.userId` (number)
    User ID if the share is a user share.
    Example: 9876543210

  - `result.groupId` (number)
    Group ID if the share is a group share.
    Example: 1234567890

  - `result.name` (string)
    If present, the name of the user or group to which the asset is shared.
    Example: "Example Name"

  - `result.type` (string, required)
    The type of this share. One of the following values: GROUP or USER.
    Example: "USER"

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

  - `result.scope` (string, required)
    The scope of this share. One of the following values:
  * ITEM: an item-level share (that is, the specific object to which the share applies is shared with
    the user or group).
  * WORKSPACE: a workspace-level share (that is, the workspace that contains the asset to which the
    share applies is shared with the user or group).
    Enum: "ITEM", "WORKSPACE"

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