Skip to main content
Version: Insiders

Manage Guest Templates, Policies, and Owners

The EasyLife 365 Collaboration Insiders API reads guest accounts and changes their templates, policies and owners. You can call it as a signed-in administrator or as an application. For the application setup, see Call the API as an application.

Routes​

MethodRouteWhat it doesDelegated scopeApplication rolesRate limitResponse codes
GET/admin/collab/v1/manage/guests/{guest-id}/Reads a guestConfig.ReadWrite.AllCollab.Manage.Read.All, Collab.Manage.ReadWrite.AllRead200, 400, 401, 403, 404, 429
PATCH/admin/collab/v1/manage/guests/{guest-id}/Changes the template, the policy and the ownersConfig.ReadWrite.AllCollab.Manage.ReadWrite.AllBulk200, 400, 401, 403, 404, 429

Permissions​

Permission TypePermissions
Delegated (work or school account)https://api.insiders.easylife365.cloud/admin/Config.ReadWrite.All
ApplicationCollab.Manage.ReadWrite.All for both routes, Collab.Manage.Read.All for the read
note

Collab.Manage.Read.All can read a guest. It cannot change one: a PATCH answers 403. Application permissions always require admin consent. A role of another product does not work here. See Call the API as an application.

Read a guest​

GET https://api.insiders.easylife365.cloud/admin/collab/v1/manage/guests/{guest-id}/
Authorization: Bearer {access-token}

{guest-id} is the object ID of the guest account in Microsoft Entra ID. The ID of a member of your tenant answers 404, because members are not guests.

Response​

{
"id": "6f2c8e14-3d0b-4a57-9a6e-52c1b7d94e08",
"displayName": "Alex Meyer (Fabrikam)",
"isCompliant": false,
"metadata": {
"tId": "2990ea33-02e8-4d06-9f44-9b63fc59eae3"
},
"policy": {
"pId": "ad869549-d693-4d20-8879-402d5ed3d991",
"coSta": "incompliant",
"coCh": "2026-10-12T08:30:00Z"
},
"schema": {
"templateId": "2990ea33-02e8-4d06-9f44-9b63fc59eae3",
"policyId": "ad869549-d693-4d20-8879-402d5ed3d991",
"isCompliant": false,
"hasOwners": true
}
}

metadata, policy and schema are the data EasyLife 365 stores on the guest, returned as stored. Their inner names carry no promise to stay the same, so read only the names you need. A guest's policy data includes the lifecycle state of the guest, such as an invitation that is not accepted, and counts as personal data. The owners of the guest are not part of the answer. See What a read returns.

Change a guest​

PATCH https://api.insiders.easylife365.cloud/admin/collab/v1/manage/guests/{guest-id}/
Content-Type: application/json

HTTP request headers​

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

Request body​

PropertyTypeDescription
templateIdStringID of the guest template. (Optional)
policyIdStringID of the guest policy. (Optional)
primaryOwnerIdStringEntra ID of the primary owner of the guest. (Optional)
secondaryOwnerIdStringEntra ID of the secondary owner of the guest. (Optional)
tertiaryOwnerIdStringEntra ID of the tertiary owner of the guest. (Optional)
quaternaryOwnerIdStringEntra ID of the quaternary owner of the guest. (Optional)
quinaryOwnerIdStringEntra ID of the quinary owner of the guest. (Optional)
  • All values are optional. A value you leave out is not changed.
  • To assign a template and a policy, send both values.
  • To clear a value, for example to remove a policy or an owner, send "00000000-0000-0000-0000-000000000000".
  • An owner must be a member of your tenant, not a guest. If one of the owners you name cannot be an owner, nothing is saved.
  • The same person cannot hold two owner places.

Response​

A successful call answers 200 with the guest after the change. The answer keeps every member it had before and adds isCompliant and schema. The change is recorded in the audit log, with the calling application as the actor when an application made it.

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:

StatusCodeWhen
400InvalidPayloadThe ID is empty, or the body is missing.
400Collab.TemplateNotActiveThe template is not active.
400Collab.TemplateNotApplicableThe template is not a guest template.
400Collab.PolicyNotApplicableThe policy is not a guest policy.
400Collab.OwnerNotAssignableA person you named cannot be an owner.
400Collab.RequestFailedThe change could not be processed, for example an account that is synchronized from an on-premises directory, or the same owner twice.
403NotAllowedThe role is missing, or it is the read role on a change.
404NotFoundThe guest does not exist, or the ID is a member of your tenant.
404Collab.TemplateNotFoundThe template does not exist.
404Collab.PolicyNotFoundThe policy does not exist.
{
"type": "https://docs.easylife365.cloud/errors/collab/owner-not-assignable",
"title": "The user cannot be assigned as an owner.",
"status": 400,
"detail": "The user cannot be assigned as an owner.",
"code": "Collab.OwnerNotAssignable",
"requestId": "0HNG2K4V7QJ3D:00000009"
}

Example 1: Assign a template and a policy to the guest​

This example assigns a template and a policy to the guest with ID 6f2c8e14-3d0b-4a57-9a6e-52c1b7d94e08.

PATCH https://api.insiders.easylife365.cloud/admin/collab/v1/manage/guests/6f2c8e14-3d0b-4a57-9a6e-52c1b7d94e08/
Content-Type: application/json
{
"templateId": "2990ea33-02e8-4d06-9f44-9b63fc59eae3",
"policyId": "ad869549-d693-4d20-8879-402d5ed3d991"
}

Example 2: Clear the policy of a guest​

{
"policyId": "00000000-0000-0000-0000-000000000000"
}

Example 3: Assign a primary and a secondary owner​

{
"primaryOwnerId": "00d0c474-abd1-4dda-a516-646a5046647c",
"secondaryOwnerId": "56a64fe6-4de3-4489-9719-0a3776c7399b"
}

Example 4: Read a guest as an application (curl)​

curl "https://api.easylife365.cloud/admin/collab/v1/manage/guests/6f2c8e14-3d0b-4a57-9a6e-52c1b7d94e08/" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example 5: Change the owners of a guest as an application (PowerShell)​

Get the token as shown in Call the API as an application and keep it in $accessToken.

$uri = "https://api.easylife365.cloud/admin/collab/v1/manage/guests/6f2c8e14-3d0b-4a57-9a6e-52c1b7d94e08/"

$body = @{
primaryOwnerId = "00d0c474-abd1-4dda-a516-646a5046647c"
secondaryOwnerId = "56a64fe6-4de3-4489-9719-0a3776c7399b"
} | ConvertTo-Json

$headers = @{ Authorization = "Bearer $accessToken" }

Invoke-RestMethod -Method Patch -Uri $uri -Headers $headers -ContentType "application/json" -Body $body

On the Insiders ring, use the host api.insiders.easylife365.cloud.