Edit

Share via

Create openTypeExtension

  • Article

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Caution

Existing apps that use this feature with baseTask or baseTaskList should be updated, as the to-do API set built on these resources is deprecated as of May 31, 2022. That API set will stop returning data on August 31, 2022. Please use the API set built on todoTask.

Create an open extension (openTypeExtension object) and add custom properties in a new or existing instance of a resource. You can create an open extension in a resource instance and store custom data to it all in the same operation, except for specific resources.

The table in the Permissions section lists the resources that support open extensions.

Note: If you're creating open extensions on Outlook resources, see Outlook-specific considerations in openTypeExtension resource type.

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 you're creating the extension in 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.AccessAsUser.All Not supported. Device.ReadWrite.All
driveItem Files.ReadWrite Files.ReadWrite Not supported.
event Calendars.ReadWrite Calendars.ReadWrite Calendars.ReadWrite
group Group.ReadWrite.All Not supported. Group.ReadWrite.All
group event Group.ReadWrite.All Not supported. Not supported.
group post Group.ReadWrite.All Not supported. Group.ReadWrite.All
message Mail.ReadWrite Mail.ReadWrite Mail.ReadWrite
organization Organization.ReadWrite.All Not supported. Organization.ReadWrite.All
personal contact Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
todoTask Tasks.ReadWrite Tasks.ReadWrite Not supported.
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Not supported.
user User.ReadWrite Not supported. User.ReadWrite.All
baseTask (deprecated) Tasks.ReadWrite Tasks.ReadWrite Not supported.
baseTaskList (deprecated) Tasks.ReadWrite Tasks.ReadWrite Not supported.

HTTP request

Create an extension in a new resource instance

Use the same REST request that you use to create the instance.

POST /users/{userId|userPrincipalName}/events
POST /users/{userId|userPrincipalName}/messages
POST /groups/{userId}/events
POST /groups/{userId}/threads/{threadId}/posts/{postId}/reply
POST /users/{userId|userPrincipalName}/contacts
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/todo/lists
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/tasks/lists
POST /drive/items/{itemId}/children

Note: This syntax shows some common ways to create the supported resource instances. All other POST syntaxes that allows you to create these resource instances supports creating open extensions in them in a similar way.

See the Request body section about including the properties of the new resource instance and the extension in the request body.

Create an extension in an existing resource instance

Identify the resource instance in the request and do a POST to the extensions navigation property.

POST /administrativeunits/{administrativeUnitId}/extensions
POST /devices/{deviceId}/extensions
POST /users/{userId|userPrincipalName}/events/{eventId}/extensions
POST /groups/{groupId}/extensions
POST /groups/{groupId}/events/{eventId}/extensions
POST /groups/{groupId}/threads/{threadId}/posts/{postId}/extensions
POST /users/{userId|userPrincipalName}/messages/{messageId}/extensions
POST /organization/{organizationId}/extensions
POST /users/{userId|userPrincipalName}/contacts/{contactId}/extensions
POST /users/{userId|userPrincipalName}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/extensions
POST /drive/items/{itemId}/extensions

Note: This syntax shows some common ways to identify a resource instance, in order to create an extension in it. All other syntaxes that allows you to identify these resource instances supports creating open extensions in them in a similar way.

See the Request body section about including the extension in the request body.

Request headers

Name Value
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json

Request body

Provide a JSON body of an openTypeExtension, with the following required name-value pairs and any additional custom data. The data in the JSON payload can be primitive types, or arrays of primitive types.

Name Value
@odata.type microsoft.graph.openTypeExtension
extensionName Unique string

When creating an extension in a new resource instance, in addition to the new openTypeExtension object, provide a JSON representation of the relevant properties to create such a resource instance.

Response

Response code

Depending on the operation, the response code can be 201 Created or 202 Accepted.

When you create an extension using the same operation that you use to create a resource instance, the operation returns the same response code that it returns when you use the operation to create the resource instance without the extension. Refer to the corresponding topics for creating the instance, as listed above.

Response body

Scenario Resource Response body
Creating an extension while explicitly creating a new resource instance contact, event, message Includes the new instance expanded with the openTypeExtension object.
Creating an extension while implicitly creating a resource instance post The response includes only a response code but not a response body.
Creating an extension in an existing resource instance All supported resources Includes the openTypeExtension object.

Example

Request 1

The first example creates a message and an extension in the same call. The request body includes the following:

  • The subject, body, and toRecipients properties typical of a new message.

  • And for the extension:

    • The type microsoft.graph.openTypeExtension.
    • The extension name "Com.Contoso.Referral".
    • Additional data to be stored as three custom properties in the JSON payload: companyName, expirationDate, and dealValue.
POST https://graph.microsoft.com/beta/me/messages
Content-Type: application/json

{
  "subject": "Annual review",
  "body": {
    "contentType": "HTML",
    "content": "You should be proud!"
  },
  "toRecipients": [
    {
      "emailAddress": {
        "address": "rufus@contoso.com"
      }
    }
  ],
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Response 1

Here is the response for the first example. The response body includes properties of the new message, and the following for the new extension:

  • The id property with the fully qualified name of microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • The default property extensionName specified in the request.
  • The custom data specified in the request stored as 3 custom properties.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/beta/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "id": "AAMkAGEbs88AAB84uLuAAA=",
  "createdDateTime": "2015-10-30T03:03:43Z",
  "lastModifiedDateTime": "2015-10-30T03:03:43Z",
  "changeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "categories": [ ],
  "receivedDateTime": "2015-10-30T03:03:43Z",
  "sentDateTime": "2015-10-30T03:03:43Z",
  "hasAttachments": false,
  "subject": "Annual review",
  "body": {
    "contentType": "HTML",
    "content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r
\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "bodyPreview": "You should be proud!",
  "importance": "Normal",
  "parentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "sender": null,
  "from": null,
  "toRecipients": [
    {
      "emailAddress": {
        "address": "rufus@contoso.com",
        "name": "John Doe"
      }
    }
  ],
  "ccRecipients": [ ],
  "bccRecipients": [ ],
  "replyTo": [ ],
  "conversationId": "AAQkAGEFGugh3SVdMzzc=",
  "isDeliveryReceiptRequested": false,
  "isReadReceiptRequested": false,
  "isRead": true,
  "isDraft": true,
  "webLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "inferenceClassification": "Focused",
  "extensions": [
    {
      "@odata.type": "#microsoft.graph.openTypeExtension",
      "@odata.id": "https://graph.microsoft.com/beta/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
      "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Request 2

The second example creates an extension in the specified message. The request body includes the following for the extension:

  • The type microsoft.graph.openTypeExtension.
  • The extension name "Com.Contoso.Referral".
  • Additional data to be stored as 3 custom properties in the JSON payload: companyName, dealValue, and expirationDate.
POST https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions
Content-Type: application/json

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Referral",
  "companyName" : "Wingtip Toys",
  "dealValue" : 500050,
  "expirationDate" : "2015-12-03T10:00:00.000Z"
}

Response 2

Here is the response for the second example. The response body includes the following for the new extension:

  • The default property extensionName.
  • The id property with the fully qualified name of microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • The custom data to be stored.
HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/beta/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
    "extensionName": "Com.Contoso.Referral",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
    "companyName": "Wingtip Toys",
    "dealValue": 500050,
    "expirationDate": "2015-12-03T10:00:00.000Z"
}

Request 3

The third example creates an extension in the specified group event. The request body includes the following for the extension:

  • The type microsoft.graph.openTypeExtension.
  • The extension name "Com.Contoso.Deal".
  • Additional data to be stored as 3 custom properties in the JSON payload: companyName, dealValue, and expirationDate.
POST https://graph.microsoft.com/beta/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions
Content-type: application/json

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Deal",
  "companyName" : "Alpine Skis",
  "dealValue" : 1010100,
  "expirationDate" : "2015-07-03T13:04:00.000Z"
}

Response 3

Here is the response from the third example request.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('f5480dfd-7d77-4d0b-ba2e-3391953cc74a')/events('AAMkADVl7IsAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Deal",
    "extensionName": "Com.Contoso.Deal",
    "companyName": "Alpine Skis",
    "dealValue": 1010100,
    "expirationDate": "2015-07-03T13:04:00Z"
}

Request 4

The fourth example creates an extension in a new group post, using the same reply action call to an existing group post. The reply action creates a new post, and a new extension embedded in the post. The request body includes a post property, which in turn contains the body of the new post, and the following data for the new extension:

  • The type microsoft.graph.openTypeExtension.
  • The extension name "Com.Contoso.HR".
  • Additional data to be stored as 3 custom properties in the JSON payload: companyName, expirationDate, and the array of strings topPicks.
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply
Content-type: application/json

{
  "post": {
    "body": {
      "contentType": "html",
      "content": "<html><body><div><div><div><div>When and where? </div></div></div></div></body></html>"
    },
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.HR",
      "companyName": "Contoso",
      "expirationDate": "2015-07-03T13:04:00.000Z",
      "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
      ]
    }
  ]
  }
}

Response 4

Here is the response from the fourth example. Successfully creating an extension in a new group post results in only the HTTP 202 response code.

HTTP/1.1 202 Accepted
Content-type: text/plain
Content-Length: 0

Request 5

The fifth example creates an extension in a new group post using the same POST operation to create a conversation. The POST operation creates a new conversation, thread and post, and a new extension embedded in the post. The request body includes the Topic and Threads properties, and a child post object for the new conversation. The post object in turn contains the body of the new post, and the following data for the extension:

  • The type microsoft.graph.openTypeExtension.
  • The extension name "Com.Contoso.HR".
  • Additional data to be stored as 3 custom properties in the JSON payload: companyName, expirationDate, and the array of strings topPicks.
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations
Content-type: application/json

{
  "Topic": "Does anyone have a second?",
  "Threads": [
    {
      "Posts": [
        {
          "Body": {
            "ContentType": "HTML",
            "Content": "This is urgent!"
          },
          "Extensions": [
            {
              "@odata.type": "microsoft.graph.openTypeExtension",
              "extensionName": "Com.Contoso.Benefits",
              "companyName": "Contoso",
              "expirationDate": "2016-08-03T11:00:00.000Z",
              "topPicks": [
                "Employees only",
                "Add spouse or guest",
                "Add family"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Response 5

Here is the response from the fifth example which contains the new conversation and a thread ID. This new thread contains an automatically created post, which in turn contains the new extension.

Note: The response object shown here might be shortened for readability.

To get the new extension, first get all the posts in this thread, and initially there should be only one. Then apply the post ID and the extension name Com.Contoso.Benefits to get the extension.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}

Request 6

The following example shows how to create an extension on an existing driveItem.

POST https://graph.microsoft.com/beta/drive/items/01FWCEC553UUOHTOAGBVE2IXBQTIZY3JZQ/extensions
Content-type: application/json

{
  "extensionName": "myCustomExtension",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}

Response 6

The following example shows the response, including the properties of the new driveItem and the following for the new extension:

  • The id property with the fully qualified name.
  • The default property extensionName specified in the request.
  • The custom data specified in the request stored as two custom properties.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "myCustomExtension",
  "extensionName": "myCustomExtension",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}

Request 7

The following example shows how to create a driveItem and an open extension for the driveItem.

POST https://graph.microsoft.com/beta/drive/items/01FWCEC553UUOHTOAGBVE2IXBQTIZY3JZQ/children
Content-type: application/json

{
  "name": "New Item",
  "@microsoft.graph.conflictBehavior": "rename",
  "extensions": [
    {
      "extensionName": "myCustomExtension",
      "myCustomString": "Contoso data",
      "myCustomBool": false
    }
  ]
}

Response 7

The following example shows the response, including properties of the new driveItem and the following for the new extension:

  • The id property with the fully qualified name.
  • The default property extensionName specified in the request.
  • The custom data specified in the request stored as two custom properties.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "ACEA49D1-1444-45A9-A1CB-68B1B28AE491",
  "createdDateTime": "2022-08-30T22:55:29Z",
  "name": "New Folder",
  "extensions": [
    {
      "id": "myCustomExtension",
      "extensionName": "myCustomExtension",
      "myCustomString": "Contoso data",
      "myCustomBool": false
    }
  ]
}