We are thrilled to share with you that Powell Teams is now Powell Governance, marking our expanded focus on Microsoft 365!
Expect documentation to be reflect this change in the coming days. For more information, please have a look at this article.
Introduction
One of the keypoint of the Powell Governance strategy is to open the product thanks to our public API and improve our interoperability with your everyday tools. You developed several tools and features to enhance this:
You will find in this article some examples showing how the Powell Governance API endpoints could be used in your everyday governance tasks around Microsoft Teams.
All technical API documentation is available on this page.
Table of content
2. Create a team based on a template
3. Update multiple teams and apply a template to them
5. Reports
6. More endpoints available in the API
1. List of the endpoints
The entire list of endpoints is updated on the API documentation: https://docapiteams.powell-software.com/#api=public-powell-teams-api-beta
2. Create a team based on a template
To illustrate the available endpoints of the API, we will take a simple business case example.
As a sales manager, you want to create a team when you reach a certain step in your sales process. Discover the replay of the webinar made on our API.
GET /beta/template
First of all, you need the template ID that you will use for this team creation. In this case, you will use your "Sales RFP" template. Use the GET beta/template endpoint and execute it. You can see below an example of the answer that includes all information about your templates: the tags, the default owners, and members of the reference team, for example. You will need the template id (in bold) to fill it in the team creation process.
{
"correlationId": null,
"errorCode": 0,
"errorMessage": null,
"isSucceed": true,
"result": [
{
"id": "e4bk9c26-a611-38bd-bp04-08f7c0d37g9d",
"additionalMembers": [],
"additionalOwners": [],
"approvers": [],
"categories": [],
"description": "A dedicated template for our RFP deals in progress",
"displayName": "RFP Template",
"isPublished": true,
"lastSchemaSynchronisation": "2020-08-26T07:46:22.8600000Z",
"minimumMembers": 0,
"minimumOwners": 2,
"namingConventionId": null,
"tagSettings": [
{
"id": "f3871661-5d1e-40d2-7814-08d7cfd5d131",
"defaultValue": "75d6b503-f396-4715-9e44-9a8e14070fb6",
"choiceValue": null,
"type": "choice",
"tagId": "5f7500b0-6d5f-49d3-c46c-08d7cfd5bbf9",
"isMandatory": true,
"isShownToUsers": true,
"choiceText": null,
"name": null,
"value": null,
"isMultiValueChoice": false
},
{
"id": "21faae5c-d90d-4efd-7815-08d7cfd5d131",
"defaultValue": "460c716b-46fd-47f2-8c50-65d4e55c03c0",
"choiceValue": null,
"type": "choice",
"tagId": "6e6c137d-e2b3-407a-c46b-08d7cfd5bbf9",
"isMandatory": true,
"isShownToUsers": true,
"choiceText": null,
"name": null,
"value": null,
"isMultiValueChoice": false
},
{
"id": "fac260f6-c340-4ed6-7816-08d7cfd5d131",
"defaultValue": "",
"choiceValue": null,
"type": "choice",
"tagId": "7fd31d09-62b5-42da-c46d-08d7cfd5bbf9",
"isMandatory": true,
"isShownToUsers": true,
"choiceText": null,
"name": null,
"value": null,
"isMultiValueChoice": false
}
],
"teamIdToClone": "1b25613d-08d3-4c1d-b57e-ee8139a24a88",
"teamsCount": 187,
"visibility": 0
},
{
"id": "6e5e0281-48c5-4d39-8822-08d879b1e04e",
"additionalMembers": [
"7ab815a1-3af6-4d80-86ef-3610e1666af8",
"3f1f5b61-a788-4028-a908-9e7b4cddc1ff",
"cf48c9d3-08c5-4613-b40f-868e0b58d7cf",
"93716ec1-c469-4dc1-9346-16a9c642a800"
],
"additionalOwners": [
"dd36000a-3744-451a-9d8b-f43cbef03e32"
GET /beta/Tags
To get the list of existing tags with their values and ID, It will be useful to get those tags IDs to create a team. Find below an example of a tag created to sort teams by geographical zones:
{
"correlationId": null,
"errorCode": 0,
"errorMessage": null,
"isSucceed": true,
"result": [
{
"choicesJson": "[{\"Id\":\"460c716b-46fd-47f2-8c50-65d4e55c03c0\",\"Value\":\"Global\"},{\"Id\":\"8e1aa360-2e40-4a6e-b272-b0ed0b716e25\",\"Value\":\"DACH\"},{\"Id\":\"7cd77afa-02c2-4189-8927-1a3fad33008c\",\"Value\":\"France\"},{\"Id\":\"f3d97775-95b9-48e8-a371-367b4ad3e358\",\"Value\":\"Western Europe\"},{\"Id\":\"356a1864-5b4c-4bd9-997a-0c63b30335d8\",\"Value\":\"APAC\"},{\"Id\":\"e195ae5d-1c40-42d6-bb04-c77755e776b2\",\"Value\":\"North America\"},{\"Id\":\"0b8c5c7e-d244-4c0e-bb6d-c6fd400b5a87\",\"Value\":\"United Kingdom\"},{\"Id\":\"cc9e4063-f2f0-4562-ad6f-4a94e6ebbbf6\",\"Value\":\"MEA\"}]",
"id": "6e6c137d-e2b3-407a-c46b-08d7cfd5bbf9",
"isRefiner": true,
"name": "Location",
"type": "choice"
},
POST /beta/Tags
Using this endpoint allows you to have all the information about a tag and only this tag by filling its ID. You will find the same information with the endpoint GET Beta/Tags but for a unique tag.
{
"correlationId": null,
"errorCode": 0,
"errorMessage": null,
"isSucceed": true,
"result": [
{
"id": "6e6c137d-e2b3-407a-c46b-08d7cfd5bbf9",
"name": "Location",
"type": "choice",
"isMultiValueChoice": false,
"choices": [
{
"id": "460c716b-46fd-47f2-8c50-65d4e55c03c0",
"value": "Global"
},
{
"id": "8e1aa360-2e40-4a6e-b272-b0ed0b716e25",
"value": "DACH"
},
{
"id": "7cd77afa-02c2-4189-8927-1a3fad33008c",
"value": "France"
},
{
"id": "f3d97775-95b9-48e8-a371-367b4ad3e358",
"value": "Western Europe"
},
{
"id": "356a1864-5b4c-4bd9-997a-0c63b30335d8",
"value": "APAC"
},
{
"id": "e195ae5d-1c40-42d6-bb04-c77755e776b2",
"value": "North America"
},
{
"id": "0b8c5c7e-d244-4c0e-bb6d-c6fd400b5a87",
"value": "United Kingdom"
},
{
"id": "cc9e4063-f2f0-4562-ad6f-4a94e6ebbbf6",
"value": "MEA"
}
]
}
]
}
GET /beta/Templates
This endpoint is used to know the users configured by default in a template. Here is an example of an API answer:
{
"id": "6e5e0281-48c5-4d39-8822-08d879b1e04e",
"additionalMembers": [
"7ab815a1-3af6-4d80-86ef-3610e1666af8",
"3f1f5b61-a788-4028-a908-9e7b4cddc1ff",
"cf48c9d3-08c5-4613-b40f-868e0b58d7cf",
"93716ec1-c469-4dc1-9346-16a9c642a800"
],
"additionalOwners": [
"dd36000a-3744-451a-9d8b-f43cbef03e32"
],
"approvers": [],
"categories": [],
"description": "For the onboarding of the new players in Powell Software",
"displayName": "Onboarding template",
"isPublished": true,
"lastSchemaSynchronisation": "2020-10-26T13:20:15.2420000Z",
"minimumMembers": 1,
"minimumOwners": 0,
"namingConventionId": "e3be20bc-6296-4cbc-e810-08d879b2df53",
"tagSettings": [
{
"id": "2417a89b-c8d3-429c-272f-08d879a692d6",
"defaultValue": "",
"choiceValue": null,
"type": "choice",
"tagId": "5f7500b0-6d5f-49d3-c46c-08d7cfd5bbf9",
"isMandatory": true,
"isShownToUsers": true,
"choiceText": null,
"name": null,
"value": null,
"isMultiValueChoice": false
},
{
"id": "a3858772-d468-455c-2730-08d879a692d6",
"defaultValue": "",
"choiceValue": null,
"type": "choice",
"tagId": "6e6c137d-e2b3-407a-c46b-08d7cfd5bbf9",
"isMandatory": true,
"isShownToUsers": true,
"choiceText": null,
"name": null,
"value": null,
"isMultiValueChoice": false
}
],
"teamIdToClone": "e1ff2b23-a3c9-4248-99f4-250d8fc39531",
"teamsCount": 17,
"visibility": 1
},
{
GET /beta/Teams
This endpoint is a bit different than the precedent. You will need a user ID to fill out to have the entire list of the members of the teams. The office group ID (in bold) will be useful to all the tags associated with a team.
{
"correlationId": null,
"errorCode": 0,
"errorMessage": null,
"isSucceed": true,
"result": {
"items": [
{
"id": "48d4b961-636a-47e7-11e2-08d801ab17df",
"officeGroupId": "7bf08f89-25a0-4e28-b55e-9c56c8b917a6",
"tenantId": "d3db94fc-fda1-4328-d97c-08d7aadaa522",
"displayName": "Tenant migration",
"description": "Tenant migration",
"originalTitle": "Tenant migration",
"originalIncrementOfNamingRule": 0,
"teamTemplateId": "e4bb9c26-a811-48bd-ba04-08d7cfd3799d",
"tagSettings": [],
"visibility": 1,
"additionalMembers": [],
"additionalGroupOwners": [],
"additionalGroupMembers": [],
"additionalOwners": [],
"isArchived": false,
"classification": "MBI",
"currentUserIsOwner": false,
"created": "2020-05-27T07:28:18.1133333",
"expirationStart": "0001-01-01T00:00:00",
"expirationDate": "9999-12-31T23:59:59.9999999",
"isFavorite": false,
"webUrl": null
},
GET /beta/Teams/{teamId}/Tags
This endpoint is used to get all the tags associated with a team. By filling the OfficegroupId of the team, you will have an answer like the following one.
{
"correlationId": null,
"errorCode": 0,
"errorMessage": null,
"isSucceed": true,
"result": [
{
"id": null,
"defaultValue": "460c716b-46fd-47f2-8c50-65d4e55c03c0",
"choiceValue": "[{\"Id\":\"460c716b-46fd-47f2-8c50-65d4e55c03c0\",\"Value\":\"Global\"},{\"Id\":\"8e1aa360-2e40-4a6e-b272-b0ed0b716e25\",\"Value\":\"DACH\"},{\"Id\":\"7cd77afa-02c2-4189-8927-1a3fad33008c\",\"Value\":\"France\"},{\"Id\":\"f3d97775-95b9-48e8-a371-367b4ad3e358\",\"Value\":\"Western Europe\"},{\"Id\":\"356a1864-5b4c-4bd9-997a-0c63b30335d8\",\"Value\":\"APAC\"},{\"Id\":\"e195ae5d-1c40-42d6-bb04-c77755e776b2\",\"Value\":\"North America\"},{\"Id\":\"0b8c5c7e-d244-4c0e-bb6d-c6fd400b5a87\",\"Value\":\"United Kingdom\"},{\"Id\":\"cc9e4063-f2f0-4562-ad6f-4a94e6ebbbf6\",\"Value\":\"MEA\"}]",
"type": "choice",
"tagId": "6e6c137d-e2b3-407a-c46b-08d7cfd5bbf9",
"isMandatory": true,
"isShownToUsers": false,
"choiceText": null,
"name": "Location",
"value": "460c716b-46fd-47f2-8c50-65d4e55c03c0",
"isMultiValueChoice": false
},
GET /beta/namingconventions
This endpoint is useful to know the existing naming convention of a tenant. The naming convention in our Sales RFP template example would be "🏆 RFP 🏆 - United Kingdom - User text."
{
"correlationId": null,
"errorCode": 0,
"errorMessage": null,
"isSucceed": true,
"result": [
{
"id": "e3be20bc-6296-4cbc-e810-08d879b2df53",
"configuration": [
{
"type": "admintext",
"value": "🏆 RFP 🏆 - "
},
{
"type": "usertext",
"value": "User value"
},
{
"type": "admintext",
"value": " - "
},
{
"type": "tag",
"value": "5f7500b0-6d5f-49d3-c46c-08d7cfd5bbf9"
},
{
"type": "admintext",
"value": " - "
},
{
"type": "tag",
"value": "6e6c137d-e2b3-407a-c46b-08d7cfd5bbf9"
}
],
"isMetaNamingRule": true,
"name": "RFP naming covention",
"numberIncrement": 19
},
GET beta/namingconventions/{namingId}
If you want to have the same API answer but with only a precise naming convention, fill it ID displayed in bold in the precedent API answer.
POST beta/teams
Now that you have your template-id, you need to fill it into the POST beta/teams endpoint to create a new team.
You can fill in any information about the team you want to create. This information is displayed in bold in the following code. Here I added a team title description, provided a template ID and a tag ID, and let the team visibility for "Private." Last but not least, I've added a user by writing his email address directly.
{
"Description": "Organise and close our deal with Contoso company",
"Name": "RFP | United Kingdom | Super product | Contoso",
"TeamTemplateId": "e4bk9c26-a611-38bd-bp04-08f7c0d37g9d",
"Visibility": "Private",
"AdditionalMembers": [
"string"
],
"AdditionalGroupOwners": [
"string"
],
"AdditionalGroupMembers": [
"string"
],
"AdditionalOwners": [
"plefevre@powell-software.com"
],
"TagValues": [
{
"Value": "United Kingdom",
"TagId": "6e6c137d-e2b3-407a-c46b-08d7cfd5bbf9"
}
]
}
GET /beta/jobtask/getstatus/{taskId}
Once a team creation has been launched, you can follow the creation task into the orchestration by providing its ID. It will give you back the task status: pending, succeeded, failed, warning.
3. Update multiple teams and apply a template to them
PUT /beta/teams/{teamId}
Applying a template to multiple teams is an important step while setting a governance policy. If your tenant is composed of many teams not associated with a Powell Governance template, you should use this endpoint.
You will need a team Id, template Id, and then to fill information about this template into the body.
|
{
"Description": "string",
"Name": "string",
"TeamTemplateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Visibility": "Private",
"AdditionalMembers": [
"string"
],
"AdditionalGroupOwners": [
"string"
],
"AdditionalGroupMembers": [
"string"
],
"AdditionalOwners": [
"string"
],
"TagValues": [
{
"Value": "string",
"TagId": "00000000-0000-0000-0000-000000000000"
}
]
}
|
To update multiple teams at once, you should use the batch.
POST /beta/$batch
You will need to complete the body with your request to update one team. The batch will launch the orchestration for the other teams you specified to update.
[
{
"Id": "string",
"url": "string",
"method": "string",
"body": {},
"headers": [
"string"
]
}
]
4. Manage pending approvals
GET /beta/approvals/pending
After calling this endpoint, you will get all the approval request information with the detail of the team associated with this request. You need to keep the request Id to handle the next step: accept or refuse a pending request.
{
"CorrelationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ErrorCode": 0,
"ErrorMessage": "string",
"IsSucceed": true,
"Result": [
{
"Id": "00000000-0000-0000-0000-000000000000",
"Histories": [
{
"Id": "00000000-0000-0000-0000-000000000000",
"Status": 0,
"Comment": "string",
"Creator": {
"Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Name": "string",
"AzureADId": "00000000-0000-0000-0000-000000000000",
"Email": "string",
"Role": 0,
"Language": "string",
"TenantId": "00000000-0000-0000-0000-000000000000"
},
"Created": "2021-05-11T16:28:59.737Z"
}
],
"Team": {
"Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"OfficeGroupId": "00000000-0000-0000-0000-000000000000",
"TenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"DisplayName": "string",
"Description": "string",
"OriginalTitle": "string",
"OriginalIncrementOfNamingRule": 0,
"TeamTemplateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Photo": "string",
"TagSettings": [
{
"Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"DefaultValue": "string",
"ChoiceValue": "string",
"Type": "string",
"TagId": "00000000-0000-0000-0000-000000000000",
"IsMandatory": true,
"IsShownToUsers": true,
"ChoiceText": "string",
"Name": "string",
"Value": "string",
"IsMultiValueChoice": true
}
],
"Visibility": "UserChoice",
"AdditionalMembers": [
"string"
],
"AdditionalGroupOwners": [
"string"
],
"AdditionalGroupMembers": [
"string"
],
"AdditionalOwners": [
"string"
],
"IsArchived": true,
"Classification": "string",
"CurrentUserIsOwner": true,
"Created": "2021-05-11T16:28:59.737Z",
"ExpirationStart": "2021-05-11T16:28:59.737Z",
"ExpirationDate": "2021-05-11T16:28:59.737Z",
"IsFavorite": true,
"WebUrl": "string"
},
"TenantId": "00000000-0000-0000-0000-000000000000",
"Created": "2021-05-11T16:28:59.737Z",
"Approvers": [
"string"
]
}
]
}
|
POST /beta/approvals/approve
After filling the body with the approval Id, and the status, you are able to let a comment to the requester.
{
"CorrelationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ErrorCode": 0,
"ErrorMessage": "string",
"IsSucceed": true,
"Result": {
"JobTaskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ApprovalId": "00000000-0000-0000-0000-000000000000",
"Status": "Accepted"
}
}
Once the approval request answer is sent, you will have the task Id associated with the new team creation in the response of the API.
You are also able to get the list of the past approvals of your tenant with the following endpoint:
POST /beta/approvals/
5. Reports
All the reports that you can find within Powell Governance are available in Powell Governance API. You can consume and valorize your report's data easily and safely.
You just have to send a request for any of the reports, and the API will answer you with the list of teams concerned by this specific report.
Here is an example of the "Expired teams" report answer:
GET beta/reports/expiredTeams
{
"correlationId": null,
"errorCode": 0,
"errorMessage": null,
"isSucceed": true,
"result": [{
"groupId": "00000000-0000-0000-0000-000000000000",
"creationDate": "2019-12-12T00:49:35Z",
"lastUpdateDate": "2020-01-23T00:00:00Z",
"title": "This is a team name",
"description": "This is a team description",
"photo": null,
"isArchived": false,
"isInactive": true,
"link": "https://teams.microsoft.com/l/team/19:0000000000000000000thread.skype/conversations?groupId=0140278a-d99e-496c-9d99-6f673e9e39cf&tenantId=dd4397fc-dd36-4701-a66a-4c563cf538b9",
"powellTemplateId": "00000000-0000-0000-0000-000000000000",
"powellTemplateName": "Default Template",
"ownersIds": ["00000000-0000-0000-0000-000000000000"],
"nbOwners": 1,
"membersIds": ["00000000-0000-0000-0000-000000000000"],
"nbMembers": 1,
"externalUsersIds": [],
"nbExternals": 0,
"lastChatActivity": "0001-01-01T00:00:00",
"nbChatMessages": 0,
"nbChatReplies": 0,
"chatMessageDeltaParameters": [],
"lastDocActivity": "2019-12-17T11:52:37Z",
"nbDocuments": 3,
"driveItemDeltaParameters": {
"groupId": "00000000-0000-0000-0000-000000000000",
"deltaLink": ""
},
"minimumNumberOfOwners": 2,
"minimumNumberOfMembers": 0,
"visibility": "Public",
"expirationDate": "9999-12-31T23:59:59.9999999",
"expirationStart": "0001-01-01T00:00:00",
"isNamingRuleCompliant": true,
"namingRuleName": null
},
Two of the reports can be prefiltered directly within the API request as it can also be done into the interface.
It's the case for the Inactive teams and the Teams with missing owners:
GET beta/reports/inactive teams
You can filter the teams that will be considered inactive when sending the request to the API with offsets. It will allow you to adapt the number of days you want to consider for the last access and the last file update.
https://apiteams.powell-software.com/beta/reports/inactiveTeams?lastAccessOffset=30&lastFileAccessOffset=30
GET beta/reports/teamsWithoutMinimumOwners/{numberOfMinimumOwners}
As for the Inactive teams' report, you can choose the number of owners that will be used to filter your results. If you choose "3," for example, only the teams with less than three owners will be given in the response:
https://apiteams.powell-software.com/beta/reports/inactiveTeams/{3}
6. More endpoints available in the API
GET /beta/templates/{templateId}/picture
An endpoint to get your template images. A separated endpoint for images allows us to deliver better performance when using the endpoint beta/template.