Get open extension
Namespace: microsoft.graph
Get an open extension (openTypeExtension object) identified by name or fully qualified name.
The table in the Permissions section lists the resources that support open extensions.
The following table lists the three scenarios where you can get an open extension from a supported resource instance.
GET scenario | Supported resources | Response body |
---|---|---|
Get a specific extension from a known resource instance. | Device, event, group, group event, group post, message, organization, personal contact, user, todoTask, todoTaskList. | Open extension only. |
Get a known resource instance expanded with a specific extension. | Device, event, group, group event, group post, message, organization, personal contact, user, todoTask, todoTaskList. | A resource instance expanded with the open extension. |
Find and expand resource instances with a specific extension. | Event, group event, group post, message, personal contact, task, task list. | Resource instances expanded with the open extension. |
This API is available in the following national cloud deployments.
Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissions
Depending on the resource that contains the extension and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. To learn more, including taking caution before choosing more privileged permissions, search for the following permissions in Permissions.
Supported resource | Delegated (work or school account) | Delegated (personal Microsoft account) | Application |
---|---|---|---|
device | Directory.Read.All | Not supported | Device.ReadWrite.All |
event | Calendars.Read | Calendars.Read | Calendars.Read |
group | Group.Read.All | Not supported | Group.Read.All |
group event | Group.Read.All | Not supported | Not supported |
group post | Group.Read.All | Not supported | Group.Read.All |
message | Mail.Read | Mail.Read | Mail.Read |
organization | User.Read | Not supported | Organization.Read.All |
personal contact | Contacts.Read | Contacts.Read | Contacts.Read |
todoTask | Tasks.ReadWrite | Tasks.ReadWrite | Tasks.ReadWrite.All |
todoTaskList | Tasks.ReadWrite | Tasks.ReadWrite | Tasks.ReadWrite.All |
user | User.Read | User.Read | User.Read.All |
HTTP request
This section lists the syntax for each of the three GET
scenarios described above.
Get a specific extension in a known resource instance
Use the same REST request as getting the resource instance, and identify the extension using the extensions navigation property of that instance.
GET /devices/{Id}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/events/{Id}/extensions/{extensionId}
GET /groups/{Id}/extensions/{extensionId}
GET /groups/{Id}/events/{Id}/extensions/{extensionId}
GET /groups/{Id}/threads/{Id}/posts/{Id}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/messages/{Id}/extensions/{extensionId}
GET /organization/{Id}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/contacts/{Id}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/todo/lists/{todoTaskListId}/tasks/{taskId}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/todo/lists/{todoTaskListId}/extensions/{extensionId}
Get a known resource instance expanded with a matching extension
For the event, group event, group post, message, personal contact, task, task list resource types, you can use the same REST request as getting the resource instance, look for an extension that matches a filter on its id property, and expand the instance with the extension. The response includes most of the resource properties.
GET /users/{Id|userPrincipalName}/events/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /groups/{Id}/events/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /groups/{Id}/threads/{Id}/posts/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/messages/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/contacts/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/todo/lists/{todoTaskListId}/tasks/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/todo/lists/{Id}?$expand=extensions($filter=id eq '{extensionId}')
For the device, group, organization, and user resource types, you must also use a $select
parameter to include
the id property and any other properties you want from the resource instance:
GET /devices/{Id}?$expand=extensions($filter=id eq '{extensionId}')&$select=id,{property_1},{property_n}
GET /groups/{Id}?$expand=extensions($filter=id eq '{extensionId}')&$select=id,{property_1},{property_n}
GET /organization/{Id}?$expand=extensions($filter=id eq '{extensionId}')&$select=id,{property_1},{property_n}
GET /users/{Id|userPrincipalName}?$expand=extensions($filter=id eq '{extensionId}')&$select=id,{property_1},{property_n}
Filter for resource instances expanded with a matching extension
Use the same REST request as getting a collection of the supported resource, filter the collection for instances that contain an extension with a matching id property, and expand these instances with the extension.
GET /users/{Id|userPrincipalName}/events?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
GET /groups/{Id}/events?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
GET /groups/{Id}/threads/{Id}/posts?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/messages?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/contacts?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
Note: The above syntax shows some common ways to identify a resource instance or collection, in order to get an extension from it. All other syntax that allows you to identify these resource instances or collections supports getting open extensions from them in a similar way.
Path parameters
Parameter | Type | Description |
---|---|---|
Id | string | Placeholder for a unique identifier for an object in the corresponding collection such as messages, events, contacts. Required. Not to be confused with the id property of an openTypeExtension. |
extensionId | string | Placeholder for an extension name which is a unique text identifier for an extension, or a fully qualified name which concatenates the extension type and unique text identifier. The fully qualified name is returned in the id property when you create the extension. Required. |
Optional query parameters
Make sure you apply URL encoding to the space characters in the $filter
string.
Parameter | Description | Example |
---|---|---|
$filter | Returns an extension with its id matching the extensionId parameter value. |
Request 3 |
$filter with any operator | Returns instances of a resource collection that contain an extension with its id matching the extensionId parameter value. |
Request 5 |
$expand | Expands a resource instance to include an extension. | Request 3 and request 5 |
Request headers
Name | Value |
---|---|
Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
Request body
Don't supply a request body for this method.
Response
If successful, this method returns a 200 OK
response code and openTypeExtension object in the response body.
Depending on the GET query, the exact response body differs.
Example
Request 1
The first example shows 2 ways of referencing an extension and gets the extension in the specified message. The response is the same regardless of the way used to reference the extension.
First, by its name:
GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions/Com.Contoso.Referral
Second, by its ID (fully qualified name):
GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions/Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral
Response 1
Here is the response for the first example.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
"@odata.type": "#microsoft.graph.openTypeExtension",
"@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
"extensionName": "Com.Contoso.Referral",
"id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
"companyName": "Wingtip Toys",
"dealValue": 500050,
"expirationDate": "2015-12-03T10:00:00Z"
}
Request 2
The second example references an extension by its name and gets the extension in the specified group event.
GET https://graph.microsoft.com/v1.0/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions/Com.Contoso.Deal/
Response 2
Here is the response from the second example.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('f5480dfd-7d77-4d0b-ba2e-3391953cc74a')/events('AAMkADVl7IsAAA%3D')/extensions/$entity",
"@odata.type": "#microsoft.graph.openTypeExtension",
"id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Deal",
"extensionName": "Com.Contoso.Deal",
"companyName": "Alpine Skis",
"dealValue": 1010100,
"expirationDate": "2015-07-03T13:04:00Z"
}
Request 3
The third example gets and expands the specified message by including the extension returned from a filter. The filter returns the extension that has its id matching a fully qualified name.
GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===?$expand=extensions($filter=id eq 'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')
Response 3
And here is the response from the third example. Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages/$entity",
"@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
"@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
"id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
"changeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
"categories": [
],
"createDateTime": "2015-06-19T02:03:31Z",
"lastModifiedDateTime": "2015-08-13T02:28:00Z",
"subject": "Attached is the requested info",
"bodyPreview": "See the images attached.",
"body": {
"contentType": "HTML",
"content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
},
"importance": "Normal",
"hasAttachments": true,
"parentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
"from": {
"emailAddress": {
"address": "[email protected]",
"name": "Desmond Raley"
}
},
"sender": {
"emailAddress": {
"address": "[email protected]",
"name": "Desmond Raley"
}
},
"toRecipients": [
{
"emailAddress": {
"address": "[email protected]",
"name": "Wendy Molina"
}
}
],
"ccRecipients": [
],
"bccRecipients": [
],
"replyTo": [
],
"conversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
"receivedDateTime": "2015-06-19T02:05:04Z",
"sentDateTime": "2015-06-19T02:04:59Z",
"isDeliveryReceiptRequested": false,
"isReadReceiptRequested": false,
"isDraft": false,
"isRead": true,
"webLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"inferenceClassification": "Focused",
"extensions": [
{
"@odata.type": "#microsoft.graph.openTypeExtension",
"@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
"extensionName": "Com.Contoso.Referral",
"id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
"companyName": "Wingtip Toys",
"dealValue": 500050,
"expirationDate": "2015-12-03T10:00:00Z"
}
]
}
Request 4
The fourth example references an extension by its fully qualified name and gets the extension in the specified group post.
GET https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA=/extensions/Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate
Response 4
Here is the response from the fourth example.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/threads('AAQkADJizZJpEWwqDHsEpV_KA%3D%3D')/posts('AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA%3D')/extensions/$entity",
"@odata.type": "#microsoft.graph.openTypeExtension",
"id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate",
"extensionName": "Com.Contoso.Estimate",
"companyName": "Contoso",
"expirationDate": "2015-07-03T13:04:00Z",
"[email protected]": "#Collection(String)",
"topPicks": [
"Employees only",
"Add spouse or guest",
"Add family"
]
}
Request 5
The fifth example looks at all messages in the signed-in user's mailbox to find those that contain an extension matching a filter, and
expands them by including the extension. The filter returns extensions that has the id property matching the extension name
Com.Contoso.Referral
.
GET https://graph.microsoft.com/v1.0/me/messages?$filter=Extensions/any(f:f/id eq 'Com.Contoso.Referral')&$expand=Extensions($filter=id eq 'Com.Contoso.Referral')
Response 5
In this response for the fifth example, there is only one message in the user's mailbox that has an extension with its id equal to
Com.Contoso.Referral
.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages",
"value": [
{
"@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
"@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
"id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
"changeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
"categories": [
],
"createDateTime": "2015-06-19T02:03:31Z",
"lastModifiedDateTime": "2015-08-13T02:28:00Z",
"subject": "Attached is the requested info",
"bodyPreview": "See the images attached.",
"body": {
"contentType": "HTML",
"content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
},
"importance": "Normal",
"hasAttachments": true,
"parentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
"from": {
"emailAddress": {
"address": "[email protected]",
"name": "Desmond Raley"
}
},
"sender": {
"emailAddress": {
"address": "[email protected]",
"name": "Desmond Raley"
}
},
"toRecipients": [
{
"emailAddress": {
"address": "[email protected]",
"name": "Wendy Molina"
}
}
],
"ccRecipients": [
],
"bccRecipients": [
],
"replyTo": [
],
"conversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
"receivedDateTime": "2015-06-19T02:05:04Z",
"sentDateTime": "2015-06-19T02:04:59Z",
"isDeliveryReceiptRequested": false,
"isReadReceiptRequested": false,
"isDraft": false,
"isRead": true,
"webLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"inferenceClassification": "Focused",
"extensions": [
{
"@odata.type": "#microsoft.graph.openTypeExtension",
"@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
"extensionName": "Com.Contoso.Referral",
"id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
"companyName": "Wingtip Toys",
"dealValue": 500050,
"expirationDate": "2015-12-03T10:00:00Z"
}
]
}
]
}