Getting Started with the Azure AD B2B Invite API

This post is provided by Senior App Dev Manager Nick McCollum, who introduces us to Azure Active Directory B2B collaboration.

Azure Active Directory Business to Business (B2B) Collaboration enables your business partners to selectively access your corporate applications. In the original release of the product the invitation experience required a user to craft a comma-separated value (.csv) file containing the email addresses of the business partner users to be invited to use an application. This file was uploaded to Azure Active Directory via the Azure management portal and email invitations were sent to the users contained in the file. The email invitations contained a link that allowed the user to redeem their invitation and gain access to the associated application(s). While this approach provided the basic functionality required it limited the ability to create advanced scenarios such as self-registration. In addition, the original release did not support inviting users with social media email addresses such as Facebook and Google. This prevented sharing corporate applications with small business partners who may have been leveraging social media services for email, collaboration, and document management.

The latest release of Azure AD B2B Collaboration provides many updates to address the shortcomings of the original release including a new REST API for managing the invitation process. The features of the new invitation manager API will be the focus of this article.

Accessing the Azure AD B2B Invitation Manager API

The Azure AD B2B invitation manager API is accessed via the Microsoft Graph. To create an invitation you send an HTTP POST to The body of the HTTP POST contains a JSON representation of the invitation as follows.


"invitedUserDisplayName": "string",

"invitedUserEmailAddress": "string",

"invitedUserMessageInfo": {"@odata.type": "microsoft.graph.invitedUserMessageInfo"},

"sendInvitationMessage": false,

"inviteRedirectUrl": "string"


A description of each property of the invitation is given below.






User’s full name



User’s email address



Customized invitation message details



Indicates if the invitation API should send the email invitation. Default value is false.



The URL to redirect the user to following successful redemption of the invitation

At a minimum you must provide an invitedUserEmailAddress and an inviteRedirectUrl to create an invitation.

The invitedUserMessageInfo property can be used to customize certain aspects of the invitation email message. A description of each property of the microsoft.graph.invitedUserMessageInfo type is given below.





Array of Recipient

An array of additional recipients the invitation email message should be sent to. Currently only 1 additional recipient is supported.



Customized message body you would like to send rather than the default message



ISO 639 language format. Default is en-US. Ignored if the customizedMessageBody property is populated.

By default the sendInvitationMessage property is false. To have the invitation manager API send the email message on behalf of your application set this property to true. Otherwise, you can retrieve the redemption URL from the create invitation response and send out the email invitation yourself through whatever mechanism you choose (SMTP, Exchange, SendGrid, etc.). Using this approach allows you some additional control over the registration process in a self-registration scenario where an approval is required internally before an invitation is sent.

Sending an Invitation

The example code below demonstrates how to send an invitation using the Azure AD B2B invitation manager API. As with all graph operations you will need to provide a bearer token in the Authorization header of the HTTP POST request to the invitation manager API. The sample code uses the Active Directory Authentication Library (ADAL) to obtain an access token for the Microsoft Graph prior to calling the invitation manager API. A simple class is created that contains the properties of the invitation discussed earlier. In the example, the invitedUserEmailAddress and inviteRedirectUrl are populated and the sendInvitationMessage property is set to true indicating that we want the invitation manager to send the email invitation to the user immediately.

ClientCredential credential = new ClientCredential(clientId, clientSecret);

AuthenticationResult authResult = authenticationContext.AcquireTokenAsync(resourceUrl, credential).Result;

InvitationModel invite = new InvitationModel();

invite.invitedUserEmailAddress = emailAddress;

invite.inviteRedirectUrl = redirectUrl;

invite.sendInvitationMessage = true;

using (HttpClient client = new HttpClient())


client.BaseAddress = new Uri(resourceUrl);

client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);

HttpResponseMessage response = client.PostAsJsonAsync<InvitationModel>("v1.0/invitations", invite).Result;

dynamic inviteResult = response.Content.ReadAsAsync<dynamic>().Result;

if (inviteResult.status != “Error”)


// Invite successfully sent



A dynamic object is used to store the response of the create invitation request. A JSON representation of the response is show below.


"invitedUserDisplayName": "string",

"invitedUserEmailAddress": "string",

"invitedUserMessageInfo": {"@odata.type": "microsoft.graph.invitedUserMessageInfo"},

"sendInvitationMessage": false,

"inviteRedirectUrl": "string",

"inviteRedeemUrl": "string",

"status": "string",

"invitedUser": [{"@odata.type": "microsoft.graph.user"}]


The response to a create invitation request contains all of the properties described earlier in the invitation as well as these additional properties.






The URL the user can use to redeem his invitation



The status of the invitation. Possible values include Completed, In Progress, and Error.



The guest user created in Azure AD as part of the invitation creation

An example of the default email invitation message the user will receive is shown below. The user can click the redemption link contained in the email message to redeem their invitation and access the associated application(s).


Once the invitation has been sent a guest user account is created in your organization’s Azure Active Directory to represent the invited user. If you search Azure AD through the Azure management portal, you can find this user and examine its profile as shown below.


The profile will indicate that the user is a Guest and they are an Invited User.

Wrapping Up

This post has provided you with the basic information needed to get started with the Azure AD B2B invitation manager API. In a subsequent post we will discuss how to leverage other APIs in the Microsoft Graph to assign a user to a particular application role when they register.

Premier Support for Developers provides strategic technology guidance, critical support coverage, and a range of essential services to help teams optimize development lifecycles and improve software quality.  Contact your Application Development Manager (ADM) or email us to learn more about what we can do for you.

Comments (10)

  1. P Bose says:

    Where can I find resources on AWS to Azure Migration tips?

  2. Flynn says:

    Hi there,

    Nice post! 🙂

    Im doing something very similar but I have an additional step after sending the invite to the user – Im trying to add them to a specific security group in Ad using the ‘{0}/members/$ref’ endpoint.

    In your example above, the response from the post has an “invitedUser” member, with an ‘id’ sub-property. In my example, I also get the same type of response, with a valid guid as the id. If I go and look in Azure AD, it sometimes takes up to 30 seconds for this new user to show up (and they do indeed have that same guid as their user id), even though the POST may only take 1-2 seconds to get a response.

    Is there any explanation for this delay?

    This actually creates a bit of a problem for me in the second step when I try and add them to an AD group. The initial invite seems successful, but the add to a group doesnt work unless I add an arbitrary delay of 30 seconds say….

    Any idea what the issue here is? I can’t find any mention of delays etc in the msdn documentation.


    1. Ganu says:

      Hi Flynn,

      Did you manage to get around this delay problem. I do not see them with so much delay though but not sure if this time is reliable though.
      Secondly do you know if there is a way to programmatically get the list of Azure AD guest users along with the status if invite like if they have redeemed or still in invited status.

  3. ExplorerMT says:

    is there any working example available?

  4. T.A.Schultz says:

    I am looking for a way via AzureAD cmdlets in PowerShell or the AzureAD API to find whether a guest has accepted the invitation or not. The example above from the Azure Portal changes when that occurs (Source changes to External Azure Active Directory and the Resend invitation button disappears) but can I retrieve that property programmatically? I may have overlooked a property or method somewhere but any help appreciated.

  5. scottd says:

    Thanks for the article. It looks like Azure user invites are available in the Graph API SDK for C# now, i.e. you can build a request with the Microsoft.Graph.GraphServiceClient. With it you can create a new Microsoft.Graph.Invitation object. Then call the invitation request with:
    var result = myGraphClient.Invitations.Request().AddAsync(invitation).Result;

    1. Paul says:

      Would really appreciate a link to a full sample for sending an invite using the Graph client.

  6. Chris Lawes says:

    My company has different businesses in different countries, and each have their own Azure AD and is managed by different teams. Is there a way of federating these so that we don’t have to have invites and guest accounts in each of our Azure ADs? Much like a federatin model where we trust other Azure ADs without having to have guest accounts for other users in the other Azure ADs?

  7. Roy Cornelissen says:

    Thanks for this article. I’m trying to implement this scenario using an Application token obtained through ADAL (same as described in this article). When I post the Invitation to the Graph API using that token, I’m getting a 401 Unauthorized (other calls such as creating a user work fine). When I use an end user token for an admin user it works though and the invitation is sent. Any idea what I could be missing? AFAIK I’ve set all the required permissions for the application.

Skip to main content