Skip to main content
Version: 2.52.20

Manage Group Templates and Policies

The EasyLife 365 Collaboration API reads Microsoft 365 Groups (including Teams), changes their templates and policies and deletes them. 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/groups/{group-id}/Reads a groupConfig.ReadWrite.AllCollab.Manage.Read.All, Collab.Manage.ReadWrite.AllRead200, 401, 403, 404, 429
POST/admin/collab/v1/manage/groups/batch/Reads several groupsConfig.ReadWrite.AllCollab.Manage.ReadWrite.AllRead200, 400, 401, 403, 429
PATCH/admin/collab/v1/manage/groups/{group-id}/Changes the template and the policyConfig.ReadWrite.AllCollab.Manage.ReadWrite.AllCreate, update, delete200, 400, 401, 403, 404, 429
DELETE/admin/collab/v1/manage/groups/{group-id}/Deletes the groupConfig.ReadWrite.AllCollab.Manage.ReadWrite.AllCreate, update, delete200, 400, 401, 403, 404, 429

Permissions​

Permission TypePermissions
Delegated (work or school account)https://api.easylife365.cloud/admin/Config.ReadWrite.All
ApplicationCollab.Manage.ReadWrite.All for every route, Collab.Manage.Read.All for the read of a single group
note

Collab.Manage.Read.All can read one group. It cannot read several groups at once, change a group or delete a group: those calls answer 403. Application permissions always require admin consent. A role of another product does not work here. See Call the API as an application.

Archiving, unarchiving and owner management of a group are not part of this API. They are available to signed-in administrators in the Admin Portal only.

Read a group​

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

Response​

{
"id": "57523d68-2913-4fc0-8f91-af100f37562f",
"displayName": "Project Aurora",
"description": "Workspace of the Aurora launch team",
"mail": "project-aurora@contoso.com",
"visibility": "Private",
"resourceProvisioningOptions": [ "Team" ],
"state": 1,
"isArchived": false,
"isArchivingSupported": true,
"isCompliant": true,
"metadata": {
"tId": "3b20926e-8ff5-4d8a-b0c6-ddd765df6821"
},
"policy": {
"pId": "ad869549-d693-4d20-8879-402d5ed3d991",
"coSta": "compliant"
},
"schema": {
"templateId": "3b20926e-8ff5-4d8a-b0c6-ddd765df6821",
"policyId": "ad869549-d693-4d20-8879-402d5ed3d991",
"isCompliant": true
}
}
MemberDescription
id, displayName, description, mail, visibility, resourceProvisioningOptionsThe group as it is in Microsoft 365. resourceProvisioningOptions contains Team for a Team.
stateThe archive state as a number: 0 unknown, 1 active, 2 archiving, 3 archived, 4 restoring.
isArchivedtrue when the content is not available to users. Left out when the state could not be read.
isArchivingSupportedWhether the archive method you configured can act on this group.
isCompliant, metadata, policy, schemaThe data EasyLife 365 stores on the group, left out when the group has none. See What a read returns. Their inner names carry no promise to stay the same.

Read several groups​

Send a list of group IDs. Groups that do not exist are left out of the answer. The answer is a list, and each entry has the same members as the read of a single group.

POST https://api.easylife365.cloud/admin/collab/v1/manage/groups/batch/
Content-Type: application/json
{
"ids": [
"57523d68-2913-4fc0-8f91-af100f37562f",
"9c1b7a54-6a0e-4d0b-8c58-0b7a4f1d2e33"
]
}

Change a group​

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

HTTP request headers​

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

Request body​

PropertyTypeDescription
templateIdStringID of the group template. (Optional)
policyIdStringID of the group policy. (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, send "00000000-0000-0000-0000-000000000000".
  • Owners cannot be changed with this call. A body with owner values answers 400 with the code Collab.ValidationFailed.

Response​

A successful call answers 200 with the group after the change. The answer has every member of the read above and the stored data of the group.

Delete a group​

DELETE https://api.easylife365.cloud/admin/collab/v1/manage/groups/{group-id}/
Authorization: Bearer {access-token}
warning

A delete removes the group from Microsoft 365. Collab.Manage.ReadWrite.All also allows this, together with every change on this page. Grant it only to an application that is meant to change and delete groups, and use Collab.Manage.Read.All for an application that only reads.

A successful call answers 200. Only Microsoft 365 Groups can be deleted this way. Another kind of group answers 400 with the code Collab.GroupNotUnified.

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 a batch read names no IDs.
400Collab.TemplateNotActiveThe template is not active.
400Collab.TemplateNotApplicableThe template is not a group template.
400Collab.PolicyNotApplicableThe policy is not a group policy.
400Collab.GroupNotUnifiedThe group is not a Microsoft 365 group.
400Collab.ValidationFailedThe body names owners.
403NotAllowedThe role is missing, or it is the read role on a change.
404NotFoundThe group does not exist.
404Collab.TemplateNotFoundThe template does not exist.
404Collab.PolicyNotFoundThe policy does not exist.
{
"type": "https://docs.easylife365.cloud/errors/collab/policy-not-found",
"title": "The policy does not exist.",
"status": 404,
"detail": "Policy with Id ad869549-d693-4d20-8879-402d5ed3d991 does not exist",
"code": "Collab.PolicyNotFound",
"requestId": "0HNG2K4V7QJ3D:00000005"
}

Example 1: Assign a template and a policy to a group​

This example assigns a template and a policy to the group with ID 57523d68-2913-4fc0-8f91-af100f37562f.

PATCH https://api.easylife365.cloud/admin/collab/v1/manage/groups/57523d68-2913-4fc0-8f91-af100f37562f/
Content-Type: application/json
{
"templateId": "3b20926e-8ff5-4d8a-b0c6-ddd765df6821",
"policyId": "ad869549-d693-4d20-8879-402d5ed3d991"
}

Example 2: Clear the policy of a group​

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

Example 3: Read a group as an application (curl)​

curl "https://api.easylife365.cloud/admin/collab/v1/manage/groups/57523d68-2913-4fc0-8f91-af100f37562f/" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example 4: Change a group 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/groups/57523d68-2913-4fc0-8f91-af100f37562f/"

$body = @{
templateId = "3b20926e-8ff5-4d8a-b0c6-ddd765df6821"
policyId = "ad869549-d693-4d20-8879-402d5ed3d991"
} | 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.