Skip to main content
Version: 2.100.0

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 TypePermissions (Scope)
Delegated (work or school account)https://api.easylife365.cloud/collab/App.ReadWrite.All
ApplicationNot supported.

HTTP Request

POST https://api.easylife365.cloud/collab/v1/guests/
Content-Type: application/json

HTTP Request Headers

HeaderValue
AuthorizationBearer token. (Required)
Content-Typeapplication/json

Request Body

PropertyTypeDescription
mailStringThe unique email address of the guest. (Required)
templateIdStringThe identifier for the template to be used. (Required)
metadataObjectA set of key/value pairs representing additional information. (Optional)
addToGroupsArray of StringList 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.idStringThe 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