Edit

Share via

Send a sharing invitation

  • Article

Sends a sharing invitation for a DriveItem. A sharing invitation provides permissions to the recipients and optionally sends them an email with a sharing link.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
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 /drives/{drive-id}/items/{item-id}/invite
POST /groups/{group-id}/drive/items/{item-id}/invite
POST /me/drive/items/{item-id}/invite
POST /sites/{siteId}/drive/items/{itemId}/invite
POST /users/{userId}/drive/items/{itemId}/invite

Request body

In the request body, provide a JSON object with the following parameters.

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": [ "read | write"],
  "recipients": [
    { "@odata.type": "microsoft.graph.driveRecipient" },
    { "@odata.type": "microsoft.graph.driveRecipient" }
  ],
  "message": "string"
}
Parameter Type Description
recipients Collection(DriveRecipient) A collection of recipients who will receive access and the sharing invitation.
message String A plain text formatted message that is included in the sharing invitation. Maximum length 2000 characters.
requireSignIn Boolean Specifies whether the recipient of the invitation is required to sign-in to view the shared item.
sendInvitation Boolean If true, a sharing link is sent to the recipient. Otherwise, a permission is granted directly without sending a notification.
roles Collection(String) Specify the roles that are to be granted to the recipients of the sharing invitation.

Example

This example sends a sharing invitation to a user with email address "ryan@contoso.com" with a message about a file being collaborated on. The invitation grants Ryan read-write access to the file.

HTTP Request

If successful, this method returns 200 OK response code and permission collection object in the response body.

POST /me/drive/items/{item-id}/invite
Content-type: application/json

{
  "recipients": [
    {
      "email": "ryan@contoso.com"
    }
  ],
  "message": "Here's the file that we're collaborating on.",
  "requireSignIn": true,
  "sendInvitation": true,
  "roles": [ "write" ]
}

Response

Here is an example of the response.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "grantedTo": {
        "user": {
          "displayName": "Ryan Gregg",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "ryan@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ]
    }
  ]
}

Remarks

  • Drives with a driveType of personal (OneDrive personal) cannot create or modify permissions on the root DriveItem.
  • For a list of available roles, see Roles enumeration.

Error Responses

Read the Error Responses topic for more information about how errors are returned.