Add custom data to resources using extensions

Microsoft Graph provides a single API endpoint that gives you access to rich people-centric data and insights through a number of resources like user and message. There's now a way for you to extend Microsoft Graph with your own application data. You can add custom properties to Microsoft Graph resources without requiring an external data store. For example, 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 simply add an app-specific store identifier to the user resource.

Microsoft Graph offers two types of extensions. Choose the extension type that best suits your application needs:

• Open extensions: A good way for developers to get started.
• Schema extensions: A more versatile mechanism for developers who care about storing typed data, making their schema discoverable and shareable, being able to filter, and in the future, being able to perform input data validation and authorization.

Important: You should 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.

Supported resources

The following table lists the resources that support open and schema extensions and indicates whether they have reached general availability (GA) (available in both the v1.0 and beta endpoints) or are in preview (available only in the beta endpoint).

You can use extensions on all these resources when signed-in with a work or school account. In addition, you can use extensions on these resources - event, post, group, message, contact, and user - when signed-in with a personal account.

Open extensions

Open extensions (formerly known as Office 365 data extensions) are open types that offer a flexible way to add untyped app data directly to a resource instance.

Open extensions, together with their custom data, are accessible through the extensions navigation property of the resource instance. The extensionName property is the only pre-defined, writable property in an open extension. When creating an open extension, you must assign the extensionName property a name that is unique within the tenant. One way to do this is to use a reverse domain name system (DNS) format that is dependent on your own domain, for example, Com.Contoso.ContactInfo. Do not use the Microsoft domain (Com.Microsoft or Com.OnMicrosoft) in an extension name.

You can create an open extension in a resource instance and store custom data to it all in the same operation (note known limitation below for some of the supported resources). You can subsequently read, update, or delete the extension and its data.

Open extension example: Add custom data to users using open extensions

Schema extensions

Schema extensions allow you to define a schema you can use to extend a resource type. First, you create your schema extension definition. Then, use it to extend resource instances with strongly-typed custom data. In addition, you can control the status of your schema extension and let it be discoverable by other apps. These apps can in turn use the extension for their data and build further experiences on top of it.

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 domain that you have 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 then you can define an id of, contoso_mySchema. This is the preferred option.
• If you don’t have a verified vanity domain, you can just set the id to a schema name (without a domain name prefix), for example, mySchema. Microsoft Graph will assign a string ID for you based on the supplied name, in this format: ext{8-random-alphanumeric-chars}_{schema-name}. For example, extkvbmkofy_mySchema.

You will see this unique name in id used as the name of the complex type which will store your custom data on the extended resource instance.

Unlike open extensions, managing schema extension definitions (list, create, get, update, and delete) and managing their data (add, get, update, and delete data) are separate sets of API operations.

Since schema extensions are accessible as complex types in instances of the targeted resources, you can do CRUD operations on the custom data in a schema extension in the following ways:

• Use the resource POST method to specify custom data when creating a new resource instance.
• Use the resource GET method to read the custom data.
• Use the resource PATCH method to add or update custom data in an existing resource instance.
• Use the resource PATCH method to set the complex type to null, to delete the custom data in the resource instance.

Schema extension example: Add custom data to groups using schema extensions

Schema extensions lifecycle

When your app creates a schema extension definition, the app is marked as the owner of that schema extension.

The owner app can move the extension through different states of a lifecycle, using a PATCH operation on its status property. Depending on the current state, the owner app may be able to update or delete the extension. Any updates to a schema extension should always only be additive and non-breaking.

Supported property data types

The following data types are supported when defining a property in a schema extension:

Note: Multi-value properties are not supported.

Azure AD directory schema extensions

Azure AD supports a similar type of extensions, known as directory schema extensions, on a few directoryObject resources. While you must use Azure AD Graph API to create and manage the definitions of directory schema extensions, you can use Microsoft Graph API to add, get, update and delete data in the properties of these extensions.

Permissions

The same permissions that are required to read from or write to a specific resource are also required to read from or write to any extensions data on that resource. For example, for an app to be able to update the signed-in user's profile with custom app data, the app must have been granted the User.ReadWrite.All permission.

Additionally, to create and manage schema extension definitions, an application must be granted the Directory.AccessAsUser.All permission.

Data limits

Open extension limits

The following limits apply to directory resources (such as user, group, device):

• Each open extension can have up to 2KB of data (including the extension definition itself).
• An application can add up to two open extensions per resource instance.

Schema extension limits

An application may create no more than five schema extension definitions.

Known limitations

For known limitations using extensions, see the extensions section in the known issues article.

Extension examples

Add custom data to users using open extensions

Add custom data to groups using schema extensions

See also

Office 365 domains

Adding and verifying a domain for an Office 365 tenant