Send a sharing invitation

Sends a sharing invitation for a DriveItem. A sharing invitation provides permissions to the recipients and optionally sends an email to the recipients to notify them the item was shared.


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 /me/drive/items/{item-id}/invite
POST /drive/items/{item-id}/invite
POST /drives/{drive-id}/items/{item-id}/invite
POST /groups/{group-id}/drive/items/{item-id}/invite

Request body

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

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 where the recipient of the invitation is required to sign-in to view the shared item.
sendInvitation Boolean Specifies if an email or post is generated (false) or if the permission is just created (true).
roles Collection(String) Specify the roles that are be granted to the recipients of the sharing invitation.


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


Here is an example of how to call this API.


Here is an example of the request.

Content-type: application/json

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

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": "",
        "signInRequired": true
      "roles": [ "write" ]


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