Microsoft Graph provides a single API endpoint to access rich people-centric data and insights through resources such as user and message. You can also extend Microsoft Graph by adding custom properties to resource instances without requiring an external data store.
This article describes how Microsoft Graph supports extending its resources, the options available to add custom properties, and when to use them.
Important
Do not use extensions to store sensitive personally identifiable information, such as account credentials, government identification numbers, cardholder data, financial account data, healthcare information, or sensitive background information.
As an ISV developer, you might decide to keep your app lightweight and store app-specific user profile data in Microsoft Graph by extending the user resource.
Alternatively, you might want to retain your app's existing user profile store, and add an app-specific identifier to the user resource.
As an enterprise developer, the in-house applications that you build might rely on your organization's HR-specific data. Integration within multiple applications can be simplified by storing this custom data in Microsoft Graph.
Custom data options in Microsoft Graph
Microsoft Graph offers four types of extensions for adding custom data.
Extension attributes
Directory (Microsoft Entra ID) extensions
Schema extensions
Open extensions
Extension attributes
Microsoft Entra ID offers a set of 15 extension attributes with predefined names on the user and device resources. These properties were initially custom attributes provided in on-premises Active Directory (AD) and Microsoft Exchange. However, they can now be used for more than syncing on-premises AD and Microsoft Exchange data to Microsoft Entra ID through Microsoft Graph.
Developer experience
You can use the 15 extension attributes to store String values on user or device resource instances, through the onPremisesExtensionAttributes and extensionAttributes properties respectively. You can assign the values while creating a new resource instance or while updating an existing resource instance. You can also filter by the values.
Add or update data in extension attributes
The following example shows how to store data in extensionAttribute1 and delete existing data from extensionAttribute13 through an update operation with a PATCH method.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
OnPremisesExtensionAttributes
{
ExtensionAttribute1 = "skypeId.adeleVance",
ExtensionAttribute13 = null,
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewUser()
onPremisesExtensionAttributes := graphmodels.NewOnPremisesExtensionAttributes()
extensionAttribute1 := "skypeId.adeleVance"
onPremisesExtensionAttributes.SetExtensionAttribute1(&extensionAttribute1)
extensionAttribute13 := null
onPremisesExtensionAttributes.SetExtensionAttribute13(&extensionAttribute13)
requestBody.SetOnPremisesExtensionAttributes(onPremisesExtensionAttributes)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
OnPremisesExtensionAttributes OnPremisesExtensionAttributes();
onPremisesExtensionAttributes.setExtensionAttribute1("skypeId.adeleVance");
onPremisesExtensionAttributes.setExtensionAttribute13(null);
user.setOnPremisesExtensionAttributes(onPremisesExtensionAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\User;
use Microsoft\Graph\Generated\Models\OnPremisesExtensionAttributes;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$ OnPremisesExtensionAttributes();
$onPremisesExtensionAttributes->setExtensionAttribute1('skypeId.adeleVance');
$onPremisesExtensionAttributes->setExtensionAttribute13(null);
$requestBody->setOnPremisesExtensionAttributes($onPremisesExtensionAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,onPremisesExtensionAttributes
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","onPremisesExtensionAttributes" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Select: [] string {"id","displayName","onPremisesExtensionAttributes"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "displayName", "onPremisesExtensionAttributes"};
});
Considerations for using extension attribute properties
The onPremisesExtensionAttributes object can be updated only for objects that aren't synced from on-premises AD.
The 15 extension attributes are already predefined in Microsoft Graph and their property names can't be changed. Therefore, you can't use custom names such as SkypeId for the extension attributes. Your organization must therefore track the extension attribute properties in use to avoid inadvertently overwriting their data.
Directory (Microsoft Entra ID) extensions
Directory extensions provide developers with a strongly typed, discoverable and filterable extension experience for directory objects.
Directory extensions are first registered on an application through the Create extensionProperty operation and must be explicitly targeted to specific and supported directory objects. After a user or an admin has consented to the application in the tenant, the extension properties become immediately accessible in the tenant. All authorized applications in the tenant can read and write data on any extension properties defined on an instance of the target directory object.
For the list of resource types that can be specified as target objects for a directory extension, see Comparison of extension types.
Developer experience
Directory extension definitions are managed through the extensionProperty resource and its associated methods. The data is managed through the REST API requests that you use to manage the resource instance.
Define the directory extension
Before you can add a directory extension to a resource instance, you must first define the directory extension.
Request
In the following request, 30a5435a-1871-485c-8c7b-65f69e287e7b is the object ID of the application that owns the directory extension. You can create directory extensions that store a collection of values.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ExtensionProperty
{
Name = "jobGroupTracker",
DataType = "String",
TargetObjects = new List<string>
{
"User",
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].ExtensionProperties.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewExtensionProperty()
name := "jobGroupTracker"
requestBody.SetName(&name)
dataType := "String"
requestBody.SetDataType(&dataType)
targetObjects := []string {
"User",
}
requestBody.SetTargetObjects(targetObjects)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensionProperties, err := graphClient.Applications().ByApplicationId("application-id").ExtensionProperties().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ExtensionProperty extensionProperty = new ExtensionProperty();
extensionProperty.setName("jobGroupTracker");
extensionProperty.setDataType("String");
LinkedList<String> targetObjects = new LinkedList<String>();
targetObjects.add("User");
extensionProperty.setTargetObjects(targetObjects);
ExtensionProperty result = graphClient.applications().byApplicationId("{application-id}").extensionProperties().post(extensionProperty);
A directory extension property named extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker is created with an extension name that follows the following naming convention: extension_{appId-without-hyphens}_{extensionProperty-name}.
Add a directory extension property to a target object
After defining the directory extension, you can now add it to an instance of a target object type. You can store data in the directory extension when creating a new instance of the target object or when updating an existing object. The following example shows how to store data in the directory extension when creating a new user object.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
AccountEnabled = true,
DisplayName = "Adele Vance",
MailNickname = "AdeleV",
UserPrincipalName = "AdeleV@contoso.com",
PasswordProfile = new PasswordProfile
{
ForceChangePasswordNextSignIn = false,
Password = "xWwvJ]6NMw+bWH-d",
},
AdditionalData = new Dictionary<string, object>
{
{
"extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker" , "JobGroupN"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.PostAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
user.setAccountEnabled(true);
user.setDisplayName("Adele Vance");
user.setMailNickname("AdeleV");
user.setUserPrincipalName("AdeleV@contoso.com");
PasswordProfile passwordProfile = new PasswordProfile();
passwordProfile.setForceChangePasswordNextSignIn(false);
passwordProfile.setPassword("xWwvJ]6NMw+bWH-d");
user.setPasswordProfile(passwordProfile);
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker", "JobGroupN");
user.setAdditionalData(additionalData);
User result = graphClient.users().post(user);
The request returns a 201 Created response code and a user object in the response body.
Retrieve a directory extension
The following example shows how the directory extensions and associated data are presented on a resource instance. The extension property is returned by default through the beta endpoint, but only on $select through the v1.0 endpoint.
GET https://graph.microsoft.com/beta/users?$select=id,displayName,extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker,extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker","extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable" };
});
mgc-beta users list --select "id,displayName,extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker,extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable"
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Select: [] string {"id","displayName","extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker","extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "displayName", "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker", "extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable"};
});
To update or delete the value of the directory extension for a resource instance, use the PATCH method. To delete the extension property and its associated value, set its value to null.
The following request updates the value of one directory extension and deletes another extension property.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
AdditionalData = new Dictionary<string, object>
{
{
"extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable" , null
},
{
"extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker" , "E4"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewUser()
additionalData := map[string]interface{}{
extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable := null
requestBody.SetExtension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable(&extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable)
"extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker" : "E4",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable", null);
additionalData.put("extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker", "E4");
user.setAdditionalData(additionalData);
User result = graphClient.users().byUserId("{user-id}").patch(user);
The request returns a 204 No Content response code.
Considerations for using directory extensions
If you accidentally delete a directory extension definition, any data stored in the associated property becomes undiscoverable. To recover the data, create a new directory extension definition with the same name as the deleted definition, on the same owner app.
When a definition object is deleted before the corresponding extension property is updated to null, the property counts against the 100-limit for the object.
When the definition is deleted before data in the associated extension property is deleted, there's no way to know the existence of the extension property via Microsoft Graph - even though the undiscoverable property counts against the 100-limit.
Deleting an owner app in the home tenant makes the associated directory extensions and their data undiscoverable. When you restore an owner app, it restores the directory extension definitions but doesn't make the directory extension properties or their data immediately discoverable; because restoring an app doesn't automatically restore the associated service principal in the tenant. To make the directory extension properties and their data discoverable, either create a new service principal or restore the deleted service principal. NO changes are made to other tenants where the app has been consented to.
Schema extensions
Microsoft Graph schema extensions are conceptually similar to directory extensions. First, you define your schema extension. Then, use it to extend supported resource instances with strongly typed custom properties. In addition, you can control the status of your schema extension and let it be discoverable by other apps.
When creating a schema extension definition, you must provide a unique name for its id. There are two naming options:
If you already have a vanity .com,.net, .gov, .edu or a .org domain that's verified with your tenant, you can use the domain name along with the schema name to define a unique name, in this format {domainName}_{schemaName}. For example, if your vanity domain is contoso.com, you can define an id of contoso_mySchema. This option is highly recommended.
Alternatively, you can set the id to a schema name (without a domain name prefix). For example, mySchema. Microsoft Graph assigns a string ID for you based on the supplied name, in this format: ext{8-random-alphanumeric-chars}_{schema-name}. For example, extkvbmkofy_mySchema.
The id is the name of the complex type that stores your data on the extended resource instance.
After you register a schema extension, it's available for use by all applications in the same tenant as the associated owner application (when in the InDevelopment state) or by all applications in any tenant (when in the Available state). Like directory extensions, authorized apps have the ability to read and write data on any extensions defined on the target object.
You manage the schema extension definitions and the data in the corresponding schema extension property by using separate sets of API operations. To manage the schema extension data on the extended resource instance, use the same REST request that you use to manage the resource instance.
Use POST to store data in the schema extension property when you're creating a new user.
Use PATCH to either store data in the schema extension property or update or delete the stored data.
To delete data from a property, set its value to null.
To delete data from all properties, set every property to null. If all properties are null, the schema extension object is also deleted.
To update any property, specify only the changed properties in the request body. Omitted properties are not updated and retain their previous value.
Use GET to read the schema extension properties for all users or individual users in the tenant.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new SchemaExtension
{
Id = "graphLearnCourses",
Description = "Graph Learn training courses extensions",
TargetTypes = new List<string>
{
"user",
},
Properties = new List<ExtensionSchemaProperty>
{
new ExtensionSchemaProperty
{
Name = "courseId",
Type = "Integer",
},
new ExtensionSchemaProperty
{
Name = "courseName",
Type = "String",
},
new ExtensionSchemaProperty
{
Name = "courseType",
Type = "String",
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.SchemaExtensions.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewSchemaExtension()
id := "graphLearnCourses"
requestBody.SetId(&id)
description := "Graph Learn training courses extensions"
requestBody.SetDescription(&description)
targetTypes := []string {
"user",
}
requestBody.SetTargetTypes(targetTypes)
extensionSchemaProperty := graphmodels.NewExtensionSchemaProperty()
name := "courseId"
extensionSchemaProperty.SetName(&name)
type := "Integer"
extensionSchemaProperty.SetType(&type)
extensionSchemaProperty1 := graphmodels.NewExtensionSchemaProperty()
name := "courseName"
extensionSchemaProperty1.SetName(&name)
type := "String"
extensionSchemaProperty1.SetType(&type)
extensionSchemaProperty2 := graphmodels.NewExtensionSchemaProperty()
name := "courseType"
extensionSchemaProperty2.SetName(&name)
type := "String"
extensionSchemaProperty2.SetType(&type)
properties := []graphmodels.ExtensionSchemaPropertyable {
extensionSchemaProperty,
extensionSchemaProperty1,
extensionSchemaProperty2,
}
requestBody.SetProperties(properties)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
schemaExtensions, err := graphClient.SchemaExtensions().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
SchemaExtension schemaExtension = new SchemaExtension();
schemaExtension.setId("graphLearnCourses");
schemaExtension.setDescription("Graph Learn training courses extensions");
LinkedList<String> targetTypes = new LinkedList<String>();
targetTypes.add("user");
schemaExtension.setTargetTypes(targetTypes);
LinkedList<ExtensionSchemaProperty> properties = new LinkedList<ExtensionSchemaProperty>();
ExtensionSchemaProperty extensionSchemaProperty = new ExtensionSchemaProperty();
extensionSchemaProperty.setName("courseId");
extensionSchemaProperty.setType("Integer");
properties.add(extensionSchemaProperty);
ExtensionSchemaProperty extensionSchemaProperty1 = new ExtensionSchemaProperty();
extensionSchemaProperty1.setName("courseName");
extensionSchemaProperty1.setType("String");
properties.add(extensionSchemaProperty1);
ExtensionSchemaProperty extensionSchemaProperty2 = new ExtensionSchemaProperty();
extensionSchemaProperty2.setName("courseType");
extensionSchemaProperty2.setType("String");
properties.add(extensionSchemaProperty2);
schemaExtension.setProperties(properties);
SchemaExtension result = graphClient.schemaExtensions().post(schemaExtension);
After defining the schema extension, you can now add the extension property to an instance of a target object type. You can store data in the schema extension when creating a new instance of the target object or when updating an existing object. The following example shows how to store data in the schema extension property when creating a new user object.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
using Microsoft.Kiota.Abstractions.Serialization;
var requestBody = new User
{
AccountEnabled = true,
DisplayName = "Adele Vance",
MailNickname = "AdeleV",
UserPrincipalName = "AdeleV@contoso.com",
PasswordProfile = new PasswordProfile
{
ForceChangePasswordNextSignIn = false,
Password = "xWwvJ]6NMw+bWH-d",
},
AdditionalData = new Dictionary<string, object>
{
{
"extkmpdyld2_graphLearnCourses" , new UntypedObject(new Dictionary<string, UntypedNode>
{
{
"courseId", new UntypedString("100")
},
{
"courseName", new UntypedString("Explore Microsoft Graph")
},
{
"courseType", new UntypedString("Online")
},
})
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.PostAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
user.setAccountEnabled(true);
user.setDisplayName("Adele Vance");
user.setMailNickname("AdeleV");
user.setUserPrincipalName("AdeleV@contoso.com");
PasswordProfile passwordProfile = new PasswordProfile();
passwordProfile.setForceChangePasswordNextSignIn(false);
passwordProfile.setPassword("xWwvJ]6NMw+bWH-d");
user.setPasswordProfile(passwordProfile);
HashMap<String, Object> additionalData = new HashMap<String, Object>();
extkmpdyld2GraphLearnCourses = new ();
extkmpdyld2GraphLearnCourses.setCourseId(100);
extkmpdyld2GraphLearnCourses.setCourseName("Explore Microsoft Graph");
extkmpdyld2GraphLearnCourses.setCourseType("Online");
additionalData.put("extkmpdyld2_graphLearnCourses", extkmpdyld2GraphLearnCourses);
user.setAdditionalData(additionalData);
User result = graphClient.users().post(user);
The request returns a 201 Created response code and a schemaExtension object in the response body
Update or delete a schema extension property
Use the PATCH operation to update a schema extension or delete an existing schema extension. To delete the extension property and its associated value from the resource instance, set its value to null.
The following example deletes the value of the courseId property and updates the courseType property. To delete the extkmpdyld2_graphLearnCourses extension property in its entirety, set its value to null.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
using Microsoft.Kiota.Abstractions.Serialization;
var requestBody = new User
{
AdditionalData = new Dictionary<string, object>
{
{
"extkmpdyld2_graphLearnCourses" , new UntypedObject(new Dictionary<string, UntypedNode>
{
{
"courseType", new UntypedString("Instructor-led")
},
{
"courseId", new UntypedNull()
},
})
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewUser()
additionalData := map[string]interface{}{
extkmpdyld2_graphLearnCourses := graph.New()
courseType := "Instructor-led"
extkmpdyld2_graphLearnCourses.SetCourseType(&courseType)
courseId := null
extkmpdyld2_graphLearnCourses.SetCourseId(&courseId)
requestBody.SetExtkmpdyld2_graphLearnCourses(extkmpdyld2_graphLearnCourses)
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
extkmpdyld2GraphLearnCourses = new ();
extkmpdyld2GraphLearnCourses.setCourseType("Instructor-led");
extkmpdyld2GraphLearnCourses.setCourseId(null);
additionalData.put("extkmpdyld2_graphLearnCourses", extkmpdyld2GraphLearnCourses);
user.setAdditionalData(additionalData);
User result = graphClient.users().byUserId("{user-id}").patch(user);
GET https://graph.microsoft.com/beta/users/0668e673-908b-44ea-861d-0661297e1a3e?$select=id,displayName,extkmpdyld2_graphLearnCourses
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","extkmpdyld2_graphLearnCourses" };
});
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
Select: [] string {"id","displayName","extkmpdyld2_graphLearnCourses"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "displayName", "extkmpdyld2_graphLearnCourses"};
});
A schema extension must have an owner app. Ownership of the schema extension can't be reassigned to another app.
Deleting a schema extension definition without setting the schema extension to null makes the property and its associated user data undiscoverable.
Deleting an owner app in the home tenant doesn't delete the associated schema extension definition or the property and the data it stores. The schema extension property can still be read, deleted, or updated for users. However, the schema extension definition can't be updated.
Open extensions
Microsoft Graph open extensions are open types that offer a simple and flexible way to add untyped data directly to a resource instance. These extensions aren't strongly typed, discoverable, or filterable.
Open extensions, together with their data, are accessible through the extensions navigation property of the resource instance. They allow you to group related properties for easier access and management.
You define and manage open extensions on the fly on resource instances. They're considered unique for each object, and you don't need to apply a universally consistent pattern for all objects. For example, in the same tenant:
The user object for Adele can have an open extension named socialSettings that has three properties: linkedInProfile, skypeId, and xboxGamertag.
The user object for Bruno can have no open extension property.
The user object for Alex can have an open extension named socialSettings with five properties: theme, color, language, font, and fontSize.
Create an open extension
The following example shows an open extension definition with three properties and how the custom properties and associated data are presented on a resource instance.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new OpenTypeExtension
{
OdataType = "#microsoft.graph.openTypeExtension",
ExtensionName = "com.contoso.socialSettings",
Id = "com.contoso.socialSettings",
AdditionalData = new Dictionary<string, object>
{
{
"skypeId" , "skypeId.AdeleV"
},
{
"linkedInProfile" , "www.linkedin.com/in/testlinkedinprofile"
},
{
"xboxGamerTag" , "AwesomeAdele"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Extensions.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewExtension()
extensionName := "com.contoso.socialSettings"
requestBody.SetExtensionName(&extensionName)
id := "com.contoso.socialSettings"
requestBody.SetId(&id)
additionalData := map[string]interface{}{
"skypeId" : "skypeId.AdeleV",
"linkedInProfile" : "www.linkedin.com/in/testlinkedinprofile",
"xboxGamerTag" : "AwesomeAdele",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensions, err := graphClient.Users().ByUserId("user-id").Extensions().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
OpenTypeExtension extension = new OpenTypeExtension();
extension.setOdataType("#microsoft.graph.openTypeExtension");
extension.setExtensionName("com.contoso.socialSettings");
extension.setId("com.contoso.socialSettings");
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("skypeId", "skypeId.AdeleV");
additionalData.put("linkedInProfile", "www.linkedin.com/in/testlinkedinprofile");
additionalData.put("xboxGamerTag", "AwesomeAdele");
extension.setAdditionalData(additionalData);
Extension result = graphClient.users().byUserId("{user-id}").extensions().post(extension);
The request returns a 201 Created response code and an openTypeExtension object in the response body.
Update an existing open extension
To update an open extension, you must specify all its properties in the request body. Otherwise, the unspecified properties are deleted from the open extension. You can however explicitly set a property to null to retain it in the open extension.
The following request specifies only the linkedInProfile and xboxGamerTag properties. The value of the xboxGamerTag property is being updated while the linkedInProfile property remains the same. This request also deletes the unspecified skypeId property.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Extension
{
AdditionalData = new Dictionary<string, object>
{
{
"xboxGamerTag" , "FierceAdele"
},
{
"linkedInProfile" , "www.linkedin.com/in/testlinkedinprofile"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Extensions["{extension-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewExtension()
additionalData := map[string]interface{}{
"xboxGamerTag" : "FierceAdele",
"linkedInProfile" : "www.linkedin.com/in/testlinkedinprofile",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensions, err := graphClient.Users().ByUserId("user-id").Extensions().ByExtensionId("extension-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Extension extension = new Extension();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("xboxGamerTag", "FierceAdele");
additionalData.put("linkedInProfile", "www.linkedin.com/in/testlinkedinprofile");
extension.setAdditionalData(additionalData);
Extension result = graphClient.users().byUserId("{user-id}").extensions().byExtensionId("{extension-id}").patch(extension);
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new OpenTypeExtension
{
OdataType = "#microsoft.graph.openTypeExtension",
Id = "com.contoso.socialSettings",
AdditionalData = new Dictionary<string, object>
{
{
"@odata.context" , "https://graph.microsoft.com/beta/$metadata#users('3fbd929d-8c56-4462-851e-0eb9a7b3a2a5')/extensions/$entity"
},
{
"xboxGamerTag" , "FierceAdele"
},
{
"linkedInProfile" , "www.linkedin.com/in/testlinkedinprofile"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Extensions["{extension-id}"].GetAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewExtension()
id := "com.contoso.socialSettings"
requestBody.SetId(&id)
additionalData := map[string]interface{}{
"@odata.context" : "https://graph.microsoft.com/beta/$metadata#users('3fbd929d-8c56-4462-851e-0eb9a7b3a2a5')/extensions/$entity",
"xboxGamerTag" : "FierceAdele",
"linkedInProfile" : "www.linkedin.com/in/testlinkedinprofile",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensions, err := graphClient.Users().ByUserId("user-id").Extensions().ByExtensionId("extension-id").Get(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
OpenTypeExtension extension = new OpenTypeExtension();
extension.setOdataType("#microsoft.graph.openTypeExtension");
extension.setId("com.contoso.socialSettings");
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("@odata.context", "https://graph.microsoft.com/beta/$metadata#users('3fbd929d-8c56-4462-851e-0eb9a7b3a2a5')/extensions/$entity");
additionalData.put("xboxGamerTag", "FierceAdele");
additionalData.put("linkedInProfile", "www.linkedin.com/in/testlinkedinprofile");
extension.setAdditionalData(additionalData);
Extension result = graphClient.users().byUserId("{user-id}").extensions().byExtensionId("{extension-id}").get(extension);
15 predefined attributes per user or device resource instance
100 extension values per resource instance
Maximum of five definitions per owner app
100 extension values per resource instance (directory objects only)
Two open extensions per creator app per resource instance2
Max. of 2 Kb per open extension2
For Outlook resources, each open extension is stored in a MAPI named property3
Note
1 Due to an existing service limitation, delegates cannot create open extension-appended events in shared mailbox calendars. Attempts to do so will result in an ErrorAccessDenied response.
2 These limits on open extensions apply to the following directory resources: user, group, device, and organization.
3 Each open extension is stored in a MAPI named property, which are a limited resource in a user's mailbox. This limit applies to the following Outlook resources: message, event, and contact
You can manage all extensions when you're signed in with a work or school account. Additionally, you can manage open extensions for the following resources when signed-in with a personal Microsoft account: event, post, group, message, contact, and user.
Permissions and privileges
The same privileges that your app requires to read from or write to a resource instance are also required to manage any extensions data on that resource instance. For example, in a delegated scenario, an app can only update any user's extension data if it's granted the User.ReadWrite.All permission and the signed-in user has a supported Microsoft Entra administrator role.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.