Build Microsoft 365 Copilot connectors for people data

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 that you build other Copilot connectors, by using the Microsoft Graph external connections APIs. To make sure that Microsoft 365 recognizes that your connection contains people data, follow the connection configuration and schema requirements, and register the connection as a source of profile data.

Connection configuration requirements

Copilot connectors that contain people data must have the value people in the contentCategory property of the externalConnections API.

Connection schema requirements

Microsoft 365 Copilot connectors for people data support enrichment for the following Microsoft 365 user profile entities.

• The schema must have one property with the personAccount label to be able to map the externalItem to a person.
• Properties without a label are considered custom properties.
• Labels marked with (beta) are only available in the Microsoft Graph beta endpoint.

Example schema:

{
 "baseType": "microsoft.graph.externalItem",
 "properties": [
 {
 "name": "accountInformation",
 "type": "string",
 "labels": ["personAccount"]
 },
 {
 "name": "position",
 "type": "string",
 "labels": ["personCurrentPosition"]
 },
 {
 "name": "skills",
 "type": "stringCollection",
 "labels": ["personSkills"]
 },
 {
 "name": "requisitionId",
 "type": "string",
 "description": "The user's requisition ID"
 }
 ]
}

Serialization of JSON entities

Each property, with a label, is either of type string or stringCollection, and is a JSON serialized string representation of the Microsoft 365 profile entity to be enriched.

{
 ...
 "properties": {
 "accountInformation": "{\"userPrincipalName\": \"adelev@contoso.com\"}",
 "position": "{\"detail\":{\"jobTitle\":\"ProductManager\"}}",
 "skills@odata.type": "Collection(String)",
 "skills": [
 "{\"displayName\":\"Product requirements\"}",
 "{\"displayName\":\"Customer research\"}"
 ],
 "requisitionId": "REQ-12345678"
 }
}

Registering the connection as a profile source

After you create the connection, register it 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, 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/v1.0/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.

Recommendations for people connectors

The following are guidelines and recommendations for Copilot connectors with people data, to improve reasoning and quality in Microsoft 365 Copilot chat and Copilot Search:

• Reuse as much as possible of the available properties in the profile entities, defined by the labels, instead of creating a custom property.
• For custom properties, use a property name users and agents understand. For example, use requisitionId instead of reqId.
• When you define the schema, provide a human-readable description for each custom property. Descriptions on properties with person* labels are ignored.
• For complex custom properties, use free text, Markdown, or YAML instead of JSON.

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.
• You must provide valid string encoded JSON objects for profile entities. Microsoft Graph ignores invalid values.
• Nonmatched user accounts (userPrincipalName or externalDirectoryObjectId) are ignored.
• Microsoft Graph treats any property without a label as a custom property.
• Microsoft 365 might take up to 6 hours after the connection is created before it becomes available in search, people experiences, or Copilot.
• Connections with people data don't support staged connections.
• The following labels aren't currently supported: personManager, personAssistants, personColleagues, personAlternateContacts, and personEmergencyContacts.
• The Copilot connector principal and principalCollection schema property types aren't currently supported. Use the colleagues collection of the workPosition entity to create relationships.
• The following Copilot connector schema attributes are ignored: isQueryable, isRefinable, isRetrievable, isSearchable. All data about a person is indexed by default.

Related content

• Copilot connectors API
• Community samples