Build Microsoft 365 Copilot connectors for people data (preview)

Microsoft 365 Copilot connectors for people data enable you to ingest people data and knowledge from your source systems (for example human resources, talent management, or other people systems) into Microsoft Graph. Adding people data to Microsoft Graph makes it available to Microsoft 365 Copilot and people experiences such as the profile card and people search. When you ingest your data, Copilot can reason over the data and use it to respond to user questions.

You build Microsoft 365 Copilot connectors for people data in the same way as other Copilot connectors using the Microsoft Graph external connections APIs. To ensure Microsoft 365 recognizes your connection as containing people data, you must follow certain schema requirements and register the connection as a source of profile data.

Connection schema requirements

Microsoft 365 supports the following properties for enriching people data.

To ensure Microsoft 365 recognizes your connection as containing people data, your schema must include the accounts property, with the userPrincipalName set to the user principal name and externalDirectoryObjectId set to the object ID of the organization user.

{
  "accounts": [
    {
      "userPrincipalName": "adelev@contoso.com",
      "externalDirectoryObjectId": "069f0701-ed79-4ea1-a3c6-e8dc165e2a2a"
    }
  ]
}

Registering the connection as a profile source

After you create the connection, you must register the connection as a source of profile data and add it to the list of prioritized sources.

You register the connection as a profile source by using the profile source API with sourceId set to the connection ID of your connector and the webUrl property set to an HTTPS link to either the external system or a page with additional information about the source.

After registration, you must add the connection to the list of prioritized profile sources using the Profile property settings API. Add the URL to the profile source, in the format of https://graph.microsoft.com/beta/admin/people/profileSources(sourceId='connectionId'), where connectionId is the unique connection ID of the connection, to the prioritizedSourceUrls array. This array represents the order in which Microsoft 365 composes the view of a person. If you want your connection to be the highest prioritized source, add it as the first item in the array.

Notes and limitations

• People data provided via a Copilot connector is visible to all users in the organization. Connector data is stored in the user's Microsoft 365 profile. For more information, see Microsoft 365 Copilot connectors for people data.
• You must set the access control list (ACL) on items ingested by the connector to grant access to everyone.
• The schema requires that accounts property is present to identify the user to be enriched.
• Microsoft Graph discards people data without matching userPrincipalName and externalDirectoryObjectId in the accounts entity collection.
• You must provide valid string encoded JSON objects for profile entities. Microsoft Graph ignores invalid values.
• You must always provide profile entities as an array of entities.
• Microsoft Graph treats any other properties, besides the reserved profile properties in the connection schema, as a custom property.
• Custom properties show up in profile cards as notes during the preview, but Microsoft will remove them before or at general availability.
• Microsoft 365 might take up to 48 hours after you ingest data about a person before it becomes available in search, people experiences, or Copilot.
• Connections with people data don't support staged connections.
• Indexed items in connections with people data only appear in people search.

Related content

• Copilot connectors API
• Community samples