Skip to main content
Version: 2.52.20

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.

info

The chosen template dictates whether the created resource will be a SharePoint Team Site or a SharePoint Communication Site.

Route​

MethodRouteWhat it doesDelegated scopeApplication rolesRate limitResponse codes
POST/collab/v1/spo/Creates a SharePoint site from a templateApp.ReadWrite.AllCollab.Site.Provisioning.ReadWrite.All, Collab.Provisioning.ReadWrite.AllCreate, update, delete200, 400, 401, 403, 404, 429

Permissions​

Permission TypePermissions
Delegated (work or school account)https://api.easylife365.cloud/collab/App.ReadWrite.All
ApplicationCollab.Site.Provisioning.ReadWrite.All or Collab.Provisioning.ReadWrite.All, on the EasyLife 365 Collaboration application
note

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​

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

Request Body​

PropertyTypeDescription
displayNameStringName of the SharePoint site. (Required)
descriptionStringDescription of the SharePoint site. (Optional)
templateIdStringTemplate identifier. (Required)
aliasStringAlias of the SharePoint site. (Optional)
ownersArray of StringEntra 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.)
requestorIdStringEntra 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)
metadataObjectList of key/value pairs representing additional information. (Optional)
labelIdStringSensitivity 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:

StatusCodeWhen
400Collab.OwnersNotSetAn application names no owner.
400Collab.OwnersNotInDirectoryAn owner does not exist in your tenant.
400Collab.OwnerNotAssignableAn owner is a guest account or cannot be an owner.
400Collab.RequestorRequiredThe template has an approval and the call names no requestor.
400Collab.RequestorNotFoundThe requestor does not exist in your tenant or is a guest.
400Collab.TemplateNotActiveThe template is not active.
400Collab.TemplateNotApplicableThe template is not a SharePoint site template.
400Collab.DescriptionRequiredThe template requires a description.
403NotAllowedThe token has no create role for sites.
404Collab.TemplateNotFoundThe template does not exist.
429RateLimitedMore 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 requestorId when 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.