Skip to content

driveitem-invite.md

Latest commit

 

History

History
209 lines (163 loc) · 8.01 KB

driveitem-invite.md

File metadata and controls

209 lines (163 loc) · 8.01 KB
author spgraph-docs-team
ms.date 09/10/2017
title Send an invite to access an item
ms.localizationpriority medium
ms.subservice sharepoint
description Sends a sharing invitation for a driveItem.
doc_type apiPageType

Send a sharing invitation

Namespace: microsoft.graph

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.

[!INCLUDE national-cloud-support]

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.

[!INCLUDE permissions-table]

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 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 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) Specifies the roles that are to be granted to the recipients of the sharing invitation.
expirationDateTime DateTimeOffset Specifies the dateTime after which the permission expires. For OneDrive for Business and SharePoint, xpirationDateTime is only applicable for sharingLink permissions. Available on OneDrive for Business, SharePoint, and premium personal OneDrive accounts.
password String The password set on the invite by the creator. Optional and OneDrive Personal only.
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.

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.

HTTP

POST https://graph.microsoft.com/v1.0/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" ],
  "password": "password123",
  "expirationDateTime": "2018-07-15T14:00:00.000Z"
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

CLI

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

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

{
  "value": [
    {
      "@deprecated.GrantedTo": "GrantedTo has been deprecated. Refer to GrantedToV2",
      "grantedTo": {
        "user": {
          "displayName": "Robin Danielsen",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "grantedToV2": {
        "user": {
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20",
          "displayName": "Robin Danielsen"
        },
        "siteUser": {
          "id": "1",
          "displayName": "Robin Danielsen",
          "loginName": "Robin Danielsen"
        }
      },
      "hasPassword": true,
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "robin@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

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 property values.

Error responses

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