listItem: createLink

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Create a sharing link for a listItem.

The createLink action creates a new sharing link if the specified link type doesn't already exist for the calling application. If a sharing link of the specified type already exists for the app, this action returns the existing sharing link.

listItem resources inherit sharing permissions from the list the item resides in.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Delegated (personal Microsoft account) Files.ReadWrite Files.ReadWrite.All
Application Files.ReadWrite.All Sites.ReadWrite.All

HTTP request

POST /sites/{siteId}/lists/{listId}/items/{itemId}/createLink

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

In the request body, provide a JSON representation of the parameters.

The following table shows the parameters that can be used with this action.

Property Type Description
type String The type of sharing link to create. Optional.
scope String The scope of link to create. Either anonymous, organization or users. Optional.
expirationDateTime DateTimeOffset A string with format of yyyy-MM-ddTHH:mm:ssZ of DateTime indicates the expiration time of the permission. Optional.
password String The password of the sharing link that is set by the creator. Optional.
recipients driveRecipient collection A collection of recipients who will receive access to the sharing link. Optional.
retainInheritedPermissions Boolean Optional. If true (default), any existing inherited permissions are retained on the shared item when sharing this item for the first time. If false, all existing permissions are removed when sharing for the first time.
sendNotification Boolean If true, this method sends a sharing link in an email to users specified in recipients. Applicable to OneDrive for Business and SharePoint. The default value is false. Optional.

The following values are allowed for the type parameter.

Type value Description
view Creates a read-only link to the item.
review Creates a review link to the item. This option is only available for files in OneDrive for Business and SharePoint.
edit Creates a read-write link to the item.
embed Creates an embeddable link to the item.
blocksDownload Creates a read-only link that blocks download to the item. This option is only available for files in OneDrive for Business and SharePoint.
createOnly Creates an upload-only link to the item. This option is only available for folders in OneDrive for Business and SharePoint.
addressBar Creates the default link that is shown in the browser address bars for newly created files. Only available in OneDrive for Business and SharePoint. The organization admin configures whether this link type is supported, and what features are supported by this link type.
adminDefault Creates the default link to the item as determined by the administrator of the organization. Only available in OneDrive for Business and SharePoint. The policy is enforced for the organization by the admin

Scope types

The following values are allowed for the scope parameter.

Value Description
anonymous Anyone with the link has access, without needing to sign in. This may include people outside of your organization. Anonymous link support may be disabled by an administrator.
organization Anyone signed into your organization (tenant) can use the link to get access. Only available in OneDrive for Business and SharePoint.
users Specific people in the recipients collection can use the link to get access. Only available in OneDrive for Business and SharePoint.

Response

If successful, this method returns a single permission resource in the response body that represents the requested sharing permissions.

The response is 201 Created if a new sharing link is created for the listItem or 200 OK if an existing link is returned.

Examples

The following example requests a sharing link to be created for the listItem specified by {itemId} in the list specified {listId}. The sharing link is configured to be read-only and usable by anyone with the link. For OneDrive for Business and SharePoint users, use the sendNotification parameter to create a sharing link. The sharingLink is then sent to recipients via email. All existing permissions are removed when sharing for the first time if retainInheritedPermissions is false.

Request

POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/items/{itemId}/createLink
Content-Type: application/json

{
  "type": "view",
  "scope": "anonymous",
  "password": "String",
  "recipients": [
    {
      "@odata.type": "microsoft.graph.driveRecipient"
    }
  ],
  "sendNotification": true,
  "retainInheritedPermissions": false
}

Response

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "view",
    "scope": "anonymous",
    "webUrl": "https://1drv.ms/A6913278E564460AA616C71B28AD6EB6",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  },
  "hasPassword": true
}

OneDrive for Business and SharePoint support company sharable links. These links are similar to anonymous links, except they only work for members of the owning organization. To create a company sharable link, use the scope parameter with a value of organization.

Request

POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/items/{itemId}/createLink
Content-Type: application/json

{
  "type": "edit",
  "scope": "organization"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "edit",
    "scope": "organization",
    "webUrl": "https://contoso-my.sharepoint.com/personal/ellen_contoso_com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

When you use the embed link type, the webUrl returned can be embedded in an <iframe> HTML element. When an embed link is created, the webHtml property contains the HTML code for an <iframe> to host the content.

Note: Embed links are only supported for OneDrive personal.

Request

POST https://graph.microsoft.com/beta/sites/{siteId}/lists/{listId}/items/{itemId}/createLink
Content-Type: application/json

{
  "type": "embed"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["read"],
  "link": {
    "type": "embed",
    "webHtml": "<IFRAME src=\"https://onedrive.live.com/...\"></IFRAME>",
    "webUrl": "https://onedive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

Remarks

  • To create a link based on the organization's default policy and the caller's permissions on the listItem, omit the scope and type parameters
  • Links created using this action don't expire unless a default expiration policy is enforced for the organization.
  • Links are visible in the sharing permissions for the listItem and can be removed by an owner of the listItem.
  • Links always point to the current version of a listItem unless the listItem is checked out (SharePoint only).