New SharePoint site
EasyLife 365 Collaboration API empowers users to create SharePoint sites effortlessly. These sites are fashioned based on pre-existing templates and their associated policies.
The chosen template dictates whether the created resource will be a SharePoint Team Site or a SharePoint Communication Site.
Route
| Method | Route | What it does | Delegated scope | Application roles | Rate limit | Response codes |
|---|---|---|---|---|---|---|
| POST | /collab/v1/spo/ | Creates a SharePoint site from a template | App.ReadWrite.All | Collab.Site.Provisioning.ReadWrite.All, Collab.Provisioning.ReadWrite.All | Create, update, delete | 200, 400, 401, 403, 404, 429 |
Permissions
| Permission Type | Permissions |
|---|---|
| Delegated (work or school account) | https://api.easylife365.cloud/collab/App.ReadWrite.All |
| Application | Collab.Site.Provisioning.ReadWrite.All or Collab.Provisioning.ReadWrite.All, on the EasyLife 365 Collaboration application |
The roles belong to the EasyLife 365 Collaboration application, not to the Admin Portal. A role of the manage routes, such as Collab.Manage.ReadWrite.All, does not work here, and Collab.Guest.Provisioning.ReadWrite.All does not create sites. Application permissions always require admin consent. See Call the API as an application.
HTTP Request
POST https://api.easylife365.cloud/collab/v1/spo/
Content-Type: application/json
HTTP request headers
| Header | Value |
|---|---|
| Authorization | Bearer token. (Required) |
| Content-Type | application/json |
Request Body
| Property | Type | Description |
|---|---|---|
displayName | String | Name of the SharePoint site. (Required) |
description | String | Description of the SharePoint site. (Optional) |
templateId | String | Template identifier. (Required) |
alias | String | Alias of the SharePoint site. (Optional) |
owners | Array of String | Entra IDs of the owners of the site. (Optional for a signed-in user, who is added automatically. Required for an application, with at least one owner.) |
requestorId | 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) |
metadata | Object | List of key/value pairs representing additional information. (Optional) |
labelId | String | Sensitivity labelId for the group. (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 serves as a unique identifier to track all activities related to the provisioning process. When a new resource is created, the corresponding provisioning webhook—configured in the template—receives a payload that includes this requestId.
As part of the provisioning process, EasyLife 365 creates a Security Group linked to the provisioned SharePoint Site. This group is typically available within 15–20 seconds after the provisioning is complete via the EasyLife API.
To ensure reliable access to the provisioned group, we recommend implementing a polling mechanism as follows:
- Start polling: 20 seconds after the initial provisioning request
- Retry interval: Every 10 seconds
- Fallback timeout: Stop polling after 30 seconds if the group is not yet available
You can retrieve the provisioned group using the Microsoft Graph API with the following query (replace the requestId with your requestId):
GET https://graph.microsoft.com/v1.0/groups?$filter=easylife365_group/requestId eq '72d2f4b8-76fe-4140-9460-3c7ef9091cb5'&$select=id,displayName,easylife365_group
Content-Type: application/json
Example response
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(id,displayName,easylife365_group)",
"value": [
{
"id": "b5967fe9-fc1b-4415-9103-04694c79a758",
"displayName": "SG_EL_SPO_cc99d8a0_bb8d_4784_9ff6_841623e4458b",
"easylife365_group": {
"extensionAttribute1": "cc99d8a0-bb8d-4784-9ff6-841623e4458b",
"extensionAttribute3": "https://contoso.sharepoint.com/sites/sharepointsite"
}
}
]
}
extensionAttribute1: Contains the Graph Site ID associated with the SharePoint site.extensionAttribute3: Contains the URL of the provisioned SharePoint site.
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.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 SharePoint site template. |
| 400 | Collab.DescriptionRequired | The template requires a description. |
| 403 | NotAllowed | The token has no create role for sites. |
| 404 | Collab.TemplateNotFound | The template does not exist. |
| 429 | RateLimited | More than 4 calls in 10 seconds. Wait and try again. |
{
"type": "https://docs.easylife365.cloud/errors/collab/requestor-required",
"title": "A request that needs approval must name the person who made it.",
"status": 400,
"detail": "A request that needs approval must name the person who made it.",
"code": "Collab.RequestorRequired",
"requestId": "0HNG2K4V7QJ3D:00000015"
}
Create a site as an application
An application has no signed-in user, so nothing is taken from "who is calling":
- Name at least one owner in
owners. The application never becomes an owner. - Name the requestor in
requestorIdwhen the template has an approval. A requestor you name also becomes an owner of the site. - Without a requestor, the first owner stands in. That person becomes a site owner and gets the "your site is ready" mail.
- The template, the naming rules and the approval work as in the Admin Portal. A site that needs approval is only created after it is approved.
- A site is recorded once in the audit log, when it exists. The entry names the requestor. See Audit log.
Example 1: Create a SharePoint site
The following sample creates a SharePoint site with two owners. A signed-in user who makes the call becomes an owner as well. An application is never made an owner.
POST https://api.easylife365.cloud/collab/v1/spo/
Content-Type: application/json
{
"displayName": "My Demo SharePoint Site",
"description": "A demonstration of SharePoint site creation via the API.",
"templateId": "fc6ffbd8-f7f0-4c05-b707-227d233b9e1b",
"alias": "",
"owners": [
"49cf935a-284f-4c84-8df7-a5b11f1be527",
"6a95c23b-cbb3-4f06-9b05-5e96ac65c78c"
],
"metadata": {
"el-text-388": "Custom text field content goes here!"
}
}
Example 2: Create a SharePoint Site using PowerShell
The next example illustrates creating a SharePoint site using PowerShell. Prior to execution, ensure you've registered an application and obtained the TenantId and ClientId. Additionally, retrieve the correct 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
$body = @{
displayName = "My Demo SharePoint Site"
description = "A demonstration of SharePoint site creation via the API."
templateId = "fc6ffbd8-f7f0-4c05-b707-227d233b9e1b"
alias = ""
owners= @("49cf935a-284f-4c84-8df7-a5b11f1be527", "6a95c23b-cbb3-4f06-9b05-5e96ac65c78c")
metadata = @{
"el-text-388" = "Custom text field content goes here!"
}
}
# 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 "Creating SharePoint site with: $jsonBody" -InformationAction Continue
$response = Invoke-RestMethod -Method post -Uri $uri -Headers $headers -Body $encodedBody
$response
Example 3: Create a SharePoint site 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.easylife365.cloud/collab/v1/spo/
Content-Type: application/json
{
"displayName": "Project Aurora",
"description": "Site of the Aurora launch team",
"templateId": "fc6ffbd8-f7f0-4c05-b707-227d233b9e1b",
"owners": [
"49cf935a-284f-4c84-8df7-a5b11f1be527"
],
"requestorId": "6a95c23b-cbb3-4f06-9b05-5e96ac65c78c"
}
Save the body as site.json and send it with curl:
curl -X POST "https://api.easylife365.cloud/collab/v1/spo/" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data @site.json
Or with PowerShell:
$body = @{
displayName = "Project Aurora"
description = "Site of the Aurora launch team"
templateId = "fc6ffbd8-f7f0-4c05-b707-227d233b9e1b"
owners = @("49cf935a-284f-4c84-8df7-a5b11f1be527")
requestorId = "6a95c23b-cbb3-4f06-9b05-5e96ac65c78c"
} | ConvertTo-Json
$headers = @{ Authorization = "Bearer $accessToken" }
Invoke-RestMethod -Method Post -Uri "https://api.easylife365.cloud/collab/v1/spo/" -Headers $headers -ContentType "application/json" -Body $body
The answer is the same as for a signed-in user: approvalRequired is true when the site waits for approval. On the Insiders ring, use the host api.insiders.easylife365.cloud.