Sending a Sharing Invitation

The invite action is used to add additional permissions to an existing item and optionally notify the recipient of those permissions they have access to the item via email.

Using the invite action is more secure than creating a sharing link, because the permissions are only valid for the recipient and cannot be used by others.

HTTP Request
POST /drive/items/{item-id}/invite
POST /drive/root:/{item-path}:/invite

Note: This method has a different signature for Microsoft Graph and the OneDrive API. See OneDrive API endpoint differences for more information.

Request Body

The body of the request defines the details of the sharing invitation that will be generated. The request body should be a JSON object with the following properties:

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": [ "read | write"],
  "recipients": [
    { "@odata.type": "oneDrive.recipients" },
    { "@odata.type": "oneDrive.recipients" }
  ],
  "message": "string"
}
Name Type Description
requiresSignIn boolean If true, the recipient of the invitation is required to sign-in to view the shared item.
sendInvitation boolean If true, an email is generated and sent to the recipients specified. If false then the permissions are applied but the invitation email is not sent.
roles string array A collection of the roles to be granted to the recipients.
recipients string array A collection recipient objects that will be invited.
message string A plain text formatted message that is included in the sharing invitation. Maximum length 2000 characters. Optional.
HTTP Request
POST /drive/items/{item-id}/invite
Content-Type: application/json

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": ["write"],
  "recipients": [
    { "email": "johndoe@contoso.com" },
    { "email": "accounts_team@contoso.com" }
  ],
  "message": "Here's the document I was talking about yesterday."
}
HTTP Response

If successful, this method returns a collection of Permission resources for each permission created or modified as a result of the call.

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

{
  "value":
  [
    {
      "id": "500",
      "roles": ["write"],
      "link": { },
      "invitation": { "email": "johndoe@contoso.com" }
    },
    {
      "id": "501",
      "roles": ["write"],
      "link": { },
      "invitation": { "email": "accounts_team@contoso.com" }
    }
  ]
}
Error Responses

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

Remarks

When sharing a container item using invite the added permissions are inherited to child items.