Create externalItem

Namespace: microsoft.graph.externalConnectors

Create a new externalItem object.


One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
Delegated (work or school account) ExternalItem.ReadWrite.OwnedBy, ExternalItem.ReadWrite.All
Delegated (personal Microsoft account) Not supported
Application ExternalItem.ReadWrite.OwnedBy, ExternalItem.ReadWrite.All

HTTP request

PUT /external/connections/{connection-id}/items/{item-id}

Request headers

Name Description
Authorization Bearer {token}. Required.
Content-Type application/json. Required.

Request body

In the request body, supply a JSON representation of the externalItem object.

You can specify the following properties when creating an externalItem.

Property Type Description
id String The item ID. Required.
properties The item properties. The properties object must contain at least one property. All DateTime type properties must be in ISO 8601 format. Required.
content microsoft.graph.externalConnectors.externalItemContent The external item content. Optional.
acl microsoft.graph.externalConnectors.acl collection The access control list. Required.

Properties on an externalItem should use type specifiers in the payload in the following scenarios:

  • For String type properties, if the value contains non-ASCII characters.

    "description@odata.type": "String",
    "description": "Kandierte Äpfel"
  • For all collection types.

    "categories@odata.type": "Collection(String)"
    "categories": [


    When including a property of type Collection(DateTime), you must use the type specifier Collection(DateTimeOffset).


If successful, this method returns 200 OK response code.


Example: Create a custom item


Content-type: application/json

  "acl": [
      "type": "user",
      "value": "e811976d-83df-4cbd-8b9b-5215b18aa874",
      "accessType": "grant"
      "type": "externalGroup",
      "value": "14m1b9c38qe647f6a",
      "accessType": "deny"
  "properties": {
    "title": "Error in the payment gateway",
    "priority": 1,
    "assignee": ""
  "content": {
    "value": "Error in payment gateway...",
    "type": "text"


The following is an example of the response.

HTTP/1.1 200 OK