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
| Method | Route | What it does | Delegated scope | Application roles | Rate limit | Response codes |
|---|---|---|---|---|---|---|
| GET | /admin/collab/v1/manage/groups/{group-id}/ | Reads a group | Config.ReadWrite.All | Collab.Manage.Read.All, Collab.Manage.ReadWrite.All | Read | 200, 401, 403, 404, 429 |
| POST | /admin/collab/v1/manage/groups/batch/ | Reads several groups | Config.ReadWrite.All | Collab.Manage.ReadWrite.All | Read | 200, 400, 401, 403, 429 |
| PATCH | /admin/collab/v1/manage/groups/{group-id}/ | Changes the template and the policy | Config.ReadWrite.All | Collab.Manage.ReadWrite.All | Create, update, delete | 200, 400, 401, 403, 404, 429 |
| DELETE | /admin/collab/v1/manage/groups/{group-id}/ | Deletes the group | Config.ReadWrite.All | Collab.Manage.ReadWrite.All | Create, update, delete | 200, 400, 401, 403, 404, 429 |
Permissions
| Permission Type | Permissions |
|---|---|
| Delegated (work or school account) | https://api.easylife365.cloud/admin/Config.ReadWrite.All |
| Application | Collab.Manage.ReadWrite.All for every route, Collab.Manage.Read.All for the read of a single group |
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
}
}
| Member | Description |
|---|---|
id, displayName, description, mail, visibility, resourceProvisioningOptions | The group as it is in Microsoft 365. resourceProvisioningOptions contains Team for a Team. |
state | The archive state as a number: 0 unknown, 1 active, 2 archiving, 3 archived, 4 restoring. |
isArchived | true when the content is not available to users. Left out when the state could not be read. |
isArchivingSupported | Whether the archive method you configured can act on this group. |
isCompliant, metadata, policy, schema | The 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
| Header | Value |
|---|---|
| Authorization | Bearer token. (Required) |
| Content-Type | application/json |
Request body
| Property | Type | Description |
|---|---|---|
templateId | String | ID of the group template. (Optional) |
policyId | String | ID 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
400with the codeCollab.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}
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:
| Status | Code | When |
|---|---|---|
| 400 | InvalidPayload | The ID is empty, or a batch read names no IDs. |
| 400 | Collab.TemplateNotActive | The template is not active. |
| 400 | Collab.TemplateNotApplicable | The template is not a group template. |
| 400 | Collab.PolicyNotApplicable | The policy is not a group policy. |
| 400 | Collab.GroupNotUnified | The group is not a Microsoft 365 group. |
| 400 | Collab.ValidationFailed | The body names owners. |
| 403 | NotAllowed | The role is missing, or it is the read role on a change. |
| 404 | NotFound | The group does not exist. |
| 404 | Collab.TemplateNotFound | The template does not exist. |
| 404 | Collab.PolicyNotFound | The 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.