Invite Guest
You can use EasyLife 365 Collaboration Insiders 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.
Route
| Method | Route | What it does | Delegated scope | Application roles | Rate limit | Response codes |
|---|---|---|---|---|---|---|
| POST | /collab/v1/guests/ | Invites a guest from a template | App.ReadWrite.All | Collab.Guest.Provisioning.ReadWrite.All, Collab.Provisioning.ReadWrite.All | Create, update, delete | 200, 400, 401, 403, 404, 409, 429 |
Permissions
| Permission Type | Permissions |
|---|---|
| Delegated (work or school account) | https://api.insiders.easylife365.cloud/collab/App.ReadWrite.All |
| Application | Collab.Guest.Provisioning.ReadWrite.All or Collab.Provisioning.ReadWrite.All, on the EasyLife 365 Collaboration Insiders application |
The roles belong to the EasyLife 365 Collaboration Insiders application, not to the Admin Portal. A role of the manage routes, such as Collab.Manage.ReadWrite.All, does not work here, and Collab.Site.Provisioning.ReadWrite.All does not invite guests. Application permissions always require admin consent. See Call the API as an application.
HTTP Request
POST https://api.insiders.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 for a signed-in user, who is set as primary owner if you name none. An application must name at least one owner, from primaryOwner to quinaryOwner.) |
secondaryOwner.id | String | The secondary owner of the guest. (Optional). |
tertiaryOwner.id | String | The tertiary owner of the guest. (Optional). |
quaternaryOwner.id | String | The quaternary owner of the guest. (Optional). |
quinaryOwner.id | String | The quinary owner of the guest. (Optional). |
requestor.id | String | Entra ID of the person the request is for. Only an application sends it, and it is required when the template has an approval. A signed-in user is always the requestor and this value is ignored. (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
Errors
Errors are application/problem+json with code, title, detail and requestId. The list of codes is on Call the API as an application. These are the ones you can expect here:
| Status | Code | When |
|---|---|---|
| 400 | Collab.MailAddressInvalid | The email address is missing or not valid. |
| 400 | Collab.OwnersNotSet | An application names no owner. |
| 400 | Collab.OwnersNotInDirectory | An owner does not exist in your tenant. |
| 400 | Collab.OwnerNotAssignable | An owner is a guest account or cannot be an owner. |
| 400 | Collab.RequestorRequired | The template has an approval and the call names no requestor. |
| 400 | Collab.RequestorNotFound | The requestor does not exist in your tenant or is a guest. |
| 400 | Collab.TemplateNotActive | The template is not active. |
| 400 | Collab.TemplateNotApplicable | The template is not a guest template. |
| 403 | NotAllowed | The token has no create role for guests. |
| 404 | Collab.TemplateNotFound | The template does not exist. |
| 409 | Collab.GuestInvitationAlreadyAccepted | The guest already accepted the invitation. |
| 409 | Collab.GuestInvitedByOther | Another person already invited the guest, and the requestor you named is not one of the guest's owners. |
| 429 | RateLimited | More than 4 calls in 10 seconds. Wait and try again. |
{
"type": "https://docs.easylife365.cloud/errors/collab/owners-not-set",
"title": "The request names no owners.",
"status": 400,
"detail": "The request names no owners.",
"code": "Collab.OwnersNotSet",
"requestId": "0HNG2K4V7QJ3D:00000018"
}
Invite a guest as an application
An application has no signed-in user, so nothing is taken from "who is calling":
- Name at least one owner, from
primaryOwnertoquinaryOwner. The application never becomes an owner. - Name the requestor in
requestor.idwhen the template has an approval. - Without a requestor, the primary owner stands in. That person appears as the sender of the invitation.
- The template and the approval work as in the Admin Portal. A guest whose template has an approval is only invited after it is approved.
- An invitation is recorded once in the audit log, when the guest is invited. The entry names the requestor. See Audit log.
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.insiders.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 URI and scope from this document.
$tenantId = "[TENANT_ID]"
$scope = "[SCOPE]"
$uri = "[URI]"
az login --tenant $tenantId | Out-Null
$accessToken = az account get-access-token `
--tenant $tenantId `
--scope $scope `
--query accessToken `
--output tsv
# 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 $($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
Example 3: Invite a guest as an application
This example uses a template with an approval, so it names the requestor. Get the token as shown in Call the API as an application, with the scope https://api.easylife365.cloud/collab/.default.
POST https://api.insiders.easylife365.cloud/collab/v1/guests/
Content-Type: application/json
{
"templateId": "2990ea33-02e8-4d06-9f44-9b63fc59eae3",
"mail": "alex.meyer@fabrikam.com",
"primaryOwner": {
"id": "1a95c23b-cbb3-4f06-9b05-5e96ac65c78c"
},
"requestor": {
"id": "6a95c23b-cbb3-4f06-9b05-5e96ac65c78c"
}
}
Save the body as guest.json and send it with curl:
curl -X POST "https://api.easylife365.cloud/collab/v1/guests/" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data @guest.json
Or with PowerShell:
$body = @{
templateId = "2990ea33-02e8-4d06-9f44-9b63fc59eae3"
mail = "alex.meyer@fabrikam.com"
primaryOwner = @{ id = "1a95c23b-cbb3-4f06-9b05-5e96ac65c78c" }
requestor = @{ id = "6a95c23b-cbb3-4f06-9b05-5e96ac65c78c" }
} | ConvertTo-Json -Depth 5
$headers = @{ Authorization = "Bearer $accessToken" }
Invoke-RestMethod -Method Post -Uri "https://api.easylife365.cloud/collab/v1/guests/" -Headers $headers -ContentType "application/json" -Body $body
On the Insiders ring, use the host api.insiders.easylife365.cloud.