Edit

invitation resource type

  • Article

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.

Represents an invitation that is used to add external users to an organization.

The invitation process uses the following flow:

  • An invitation is created
  • An invitation is sent to the invited user (containing an invitation link)
  • The invited user clicks on the invitation link, signs in and redeems the invitation and creation of the user entity representing the invited user completes
  • The user is redirected to a specific page after redemption completes

Creating an invitation will return a redemption URL in the response (inviteRedeemUrl). The create invitation API can automatically send an email containing the redemption URL to the invited user, by setting the sendInvitationMessage to true. You can also customize the message that will be sent to the invited user. Instead, if you wish to send the redemption URL through some other means, you can set the sendInvitationMessage to false and use the redeem URL from the response to craft your own communication. Currently, there is no API to perform the redemption process. The invited user has to click on the inviteRedeemUrl link sent in the communication in the step above, and go through the interactive redemption process in a browser. Once completed, the invited user becomes an external user in the organization.

Note

The invitation status is tracked using the externalUserState and the externalUserStateChangeDateTime properties on the external user resource created as part of the invitation request.

Methods

Method Return Type Description
Create invitation invitation Write properties and relationships of invitation object.

Properties

Property Type Description
invitedUserDisplayName String The display name of the user being invited.
invitedUserEmailAddress String The email address of the user being invited. Required. The following special characters are not permitted in the email address:
  • Tilde (~)
  • Exclamation point (!)
  • At sign (@)
  • Number sign (#)
  • Dollar sign ($)
  • Percent (%)
  • Circumflex (^)
  • Ampersand (&)
  • Asterisk (*)
  • Parentheses (( ))
  • Hyphen (-)
  • Plus sign (+)
  • Equal sign (=)
  • Brackets ([ ])
  • Braces ({ })
  • Backslash (\)
  • Slash mark (/)
  • Pipe (|)
  • Semicolon (;)
  • Colon (:)
  • Quotation marks (")
  • Angle brackets (< >)
  • Question mark (?)
  • Comma (,)

However, the following exceptions apply:
  • A period (.) or a hyphen (-) is permitted anywhere in the user name, except at the beginning or end of the name.
  • An underscore (_) is permitted anywhere in the user name. This includes at the beginning or end of the name.
invitedUserMessageInfo invitedUserMessageInfo Additional configuration for the message being sent to the invited user, including customizing message text, language and cc recipient list.
inviteRedirectUrl String The URL user should be redirected to once the invitation is redeemed. Required.
inviteRedeemUrl String The URL the user can use to redeem their invitation. Read-only.
invitedUserType String The userType of the user being invited. By default, this is Guest. You can invite as Member if you're are company administrator. The default is false.
resetRedemption Boolean Reset the user's redemption status and reinvite a user while retaining their user identifier, group memberships, and app assignments. This property allows you to enable a user to sign-in using a different email address from the one in the previous invitation. For more information about using this property, see Reset redemption status for a guest user (Preview).
sendInvitationMessage Boolean Indicates whether an email should be sent to the user being invited. The default is false.
status String The status of the invitation. Possible values: PendingAcceptance, Completed, InProgress, and Error

Relationships

Relationship Type Description
invitedUser user The user created as part of the invitation creation. Read-Only

JSON representation

Here is a JSON representation of the resource

{
  "id": "String",
  "invitedUserDisplayName": "String",
  "invitedUserEmailAddress": "String",
  "invitedUserMessageInfo": {"@odata.type": "microsoft.graph.invitedUserMessageInfo"},
  "sendInvitationMessage": false,
  "inviteRedirectUrl": "String",
  "inviteRedeemUrl": "String",
  "resetRedemption": false,
  "status": "String",
  "invitedUser": {"@odata.type": "microsoft.graph.user"},
  "invitedUserType": "String"
}