Invite Guest
You can utilize the EasyLife 365 Collaboration API to seamlessly invite B2B Guests. Guests are generated based on predefined templates along with their corresponding policies. Additionally, a personalized message can be included to provide context to the invitee.
Permissions
Permission Type | Permissions (Scope) |
---|---|
Delegated (work or school account) | https://api.easylife365.cloud/collab/App.ReadWrite.All |
Application | Not supported. |
HTTP Request
POST https://api.easylife365.cloud/collab/v1/guests/
Content-Type: application/json
HTTP Request Headers
Header | Value |
---|---|
Authorization | Bearer token. (Required) |
Content-Type | application/json |
Request Body
Property | Type | Description |
---|---|---|
mail | String | The unique email address of the guest. (Required) |
templateId | String | The identifier for the template to be used. (Required) |
metadata | Object | A set of key/value pairs representing additional information. (Optional) |
addToGroups | Array of String | List of Microsoft Groups or Team AzureObjectIds to which the guest will be added. The requester must be an owner of these groups, else the guest won't be added. (Optional) |
secondaryOwner.id | String | The secondary owner of the guest. (Optional) The requester is automatically set as the primary owner. |
Response
Upon queuing the request, the API will respond with the following payload:
{
"requestId": "72d2f4b8-76fe-4140-9460-3c7ef9091cb5",
"tenantId": "1840b34e-6fe7-4a56-9ad3-0b7b58c49dc7",
"approvalRequired": false
}
The requestId
can be utilized to track all activities associated with the creation process. Once the guest is created, the configured provisioning webhook on the template will receive a payload containing the corresponding requestId
.
Example 1: Invite a Guest
The following example demonstrates inviting a guest to the tenant, including metadata, and adding the guest as a member of a group. The group must be owned by the requester.
POST https://api.easylife365.cloud/collab/v1/guests/
Content-Type: application/json
{
"templateId": "2990ea33-02e8-4d06-9f44-9b63fc59eae3",
"metadata": {
"el-check-917": true
},
"addToGroups": [
"17c9aba8-b068-4b79-8b73-a491f7e0dba9"
],
"mail": "my-guests@email.address",
"secondaryOwner": {
"id": "6a95c23b-cbb3-4f06-9b05-5e96ac65c78c"
}
}
Example 2: Invite a Guest using PowerShell
The next example illustrates how to invite a guest using PowerShell. Prior to executing the script, ensure that you've registered an application and acquired the TenantId and ClientId. Also, retrieve the appropriate scope from this document.
Import-Module MSAL.PS
$msalParam = @{
tenantId = "[TENANT_ID]"
clientId = "[CLIENT_ID]"
scopes = "[SCOPE]"
}
$uri = "[URI]"
# Get JWT authentication token.
if($token){
$token = Get-MsalToken @msalParam -Silent
} else {
$token = Get-MsalToken @msalParam -DeviceCode
}
# Create object with values to pass to the API.
$body = @{
templateId = "2990ea33-02e8-4d06-9f44-9b63fc59eae3"
mail = "my-guests@email.address"
secondaryOwner = @{
id = "6a95c23b-cbb3-4f06-9b05-5e96ac65c78c"
}
}
# Invoke the API and capture responses.
$jsonBody = $body | ConvertTo-Json -Depth 5 -Compress
$encodedBody = [System.Text.Encoding]::UTF8.GetBytes($jsonBody)
$headers = @{
"Authorization"="Bearer $($token.AccessToken)"
"Content-Type" = "application/json"
}
Write-Information "Inviting guest with: $jsonBody" -InformationAction Continue
$response = Invoke-RestMethod -Method post -Uri $uri -Headers $headers -Body $encodedBody
$response