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)
primaryOwner.id	String	The primary owner of the guest. (Optional) The requester is automatically set as the primary owner if not specified.
secondaryOwner.id	String	The secondary owner of the guest. (Optional).

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 acts as a unique identifier for tracking all activities related to the provisioning process. When a new resource is created, the associated provisioning webhook—configured on the template—receives a payload that includes this specific requestId.

The provisioned Guest Account is typically available within 15–20 seconds after the provisioning process completes via the EasyLife API. To ensure reliable retrieval, we recommend implementing a polling mechanism that starts 20 seconds after the initial request, with a retry interval of 10 seconds, and a fallback timeout after 30 seconds if the group is not yet available.

You can retrieve the provisioned Guest using the Microsoft Graph API with the following query (replace the requestId with your requestId):

GET https://graph.microsoft.com/v1.0/users?$filter=easylife365_user/requestId eq '72d2f4b8-76fe-4140-9460-3c7ef9091cb5'
Content-Type: application/json

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",
  "primaryOwner": {
    "id": "1a95c23b-cbb3-4f06-9b05-5e96ac65c78c"
  },
  "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