An admin sets up a connector for Confluence Cloud, the crawl completes, the items show as indexed in the admin center — and yet no Confluence result ever appears in Copilot Chat for any user, because the inline-results admin step that turns indexed content into Copilot answers was never done. In a parallel story, a developer opens the Microsoft Graph reference looking for the endpoint to build a custom federated connector — a real-time lookup that never copies data — and discovers there is no such endpoint, because only Microsoft builds federated connectors. Before you set up or build anything called a “connector,” two facts about the connector model decide whether your effort produces Copilot results at all, and neither is obvious from the product name: there are two architecturally distinct connector types, and getting indexed content to surface in Copilot takes more than a healthy connection.

After reading this post, you will be able to:

✅ Explain the synced-versus-federated split and choose the right connector type for a given data-integration scenario

✅ Build a custom synced connector with the Copilot connectors API, including a schema carrying the three mandatory Copilot labels

✅ Identify everything that must be true — in the schema and in the admin center — before connector content appears in Copilot responses

✅ Apply the licensing table to determine which tier unlocks connector grounding and federated access for your tenant

One API, Two Names — and Why the Naming Confusion Trips People Up First

Before any architecture, clear the naming fog, because it sends readers to the wrong documentation. The product is now branded Microsoft 365 Copilot connectors. It was formerly called Microsoft Graph connectors, and both names still appear across current Microsoft documentation — the Graph API reference and the Microsoft Search docs continue to use the older term. They refer to the same technology. The rebrand created no new endpoint and no new namespace: the underlying API is still /external/connections under Microsoft Graph, at https://graph.microsoft.com/v1.0/external/connections, with the same externalConnection, schema, and externalItem resources it always had. If you bookmarked the “Microsoft Graph connectors” docs, they are still correct.

A second, more damaging confusion is with Power Platform connectors, which share the word “connector” but are a different mechanism entirely. Copilot connectors index a copy of external content into Microsoft Graph so Copilot and agents can ground answers on it; Power Platform connectors are live API bridges that a Copilot Studio agent invokes at runtime to fetch or change data in a source system. The distinction is architectural, not cosmetic.

The rule that follows from the table: use Copilot connectors to bring evergreen knowledge into the Microsoft 365 semantic index, and use Power Platform connectors to invoke live data or take actions at runtime. The two can be combined in a single agent — index a knowledge base with one, file the resulting support ticket with the other.

What this means for you: when a colleague says “connector,” confirm which of the three things they mean before you scope the work — the naming overlap hides three different integration models.

Synced or Federated — The Architectural Split Every Connector Deployment Starts With

Copilot connectors come in two types, and the choice between them is the first architectural decision, not a configuration toggle you flip later. Synced connectors crawl an external source on a recurring schedule and index a copy of its content into the Microsoft 365 semantic index; queries then hit the index, not the source. Federated connectors hold no copy — they fetch data live from the source at query time via the Model Context Protocol (MCP), so nothing is crawled and nothing is stored in Microsoft 365. That difference drives everything downstream: data residency, freshness, performance, licensing, and — critically — whether you can build one yourself.

Synced connectors themselves come in two configurations. The tenant-config variant is what an admin sets up organization-wide and is the type a developer can build a custom connector for. The self-serve variant lets individual users connect and index their own personally relevant content, scoped to that user. Federated connectors are user-scoped and, as of this writing, appear in the gallery almost entirely under a preview label.

Two lines in that table carry most of the weight. First, custom connectors can be built only for the synced tenant-config type — there is no developer API for federated connectors. Second, federated connectors are read-only: they can search and fetch but never write back to the source. If your requirement is a real-time, no-copy lookup against a system Microsoft has not already built a federated connector for, the connectors API does not offer a path — you would reach for a Power Platform connector or a Retrieval-API-backed custom app instead.

Note: Custom federated connectors are not supported through the Copilot connectors API. Only Microsoft-built federated connectors are available in the gallery. If you need a live, no-index integration with a source Microsoft has not built, plan for a different mechanism rather than a custom connector.

What this means for you: decide synced-versus-federated before you write code or file a license request, because the two types diverge on data residency, freshness, licensing, and whether a custom build is even possible.

The Data Model: Four Resource Types That Define What a Connector Knows and Who Sees It

A custom synced connector is built from four Graph resources, and understanding them in the order they appear in the build makes the lifecycle that follows read cleanly.

The externalConnection is the logical container for one external data source. It carries an id (unique, alphanumeric, maximum 32 characters), a name, a description, and a configuration block listing authorizedAppIds. The description is not decorative — it feeds grounding quality by telling Copilot what content the connector holds and when a user would reach for it, so write it as if briefing the model. The connection is also the unit an admin enables or disables in the Microsoft 365 admin center.

The schema defines the shape of the data as a flat list of up to 128 properties. Each property has a name, a type (String, DateTime, Boolean, Int, Double, Geography, or Json), and a set of behavior flags: isSearchable, isRetrievable, isQueryable, isRefinable, and labels. Of these, isSearchable matters most for Copilot — a property that is not searchable is not matched against user prompts, so its content is effectively invisible to grounding.

The externalItem is an individual piece of content. It holds an acl array (who can see it), a properties bag conforming to the schema, and a content field carrying plain text or HTML. Richer content produces better grounding — Copilot performs measurably better on content-rich items than on thin metadata.

The externalGroup represents groups that do not exist in Microsoft Entra ID — Salesforce permission sets, ServiceNow local groups, and the like — so that source-system group memberships can be honored in item ACLs without replicating those groups into Entra. It exists to serve permission trimming, which the access-control section covers.

The build always flows connection → schema → items: create the container, define the shape, then ingest content against that shape.

What this means for you: model your description and your content fields as grounding inputs, not filler — they are the difference between a connector that answers well and one that indexes silently.

Semantic Labels: The Three You Must Apply and What the Full List Makes Possible

Semantic labels tell Microsoft 365 what each schema property means — which property is the title, which is the URL, which is the last-modified date — so that Search and Copilot can use them intelligently rather than treating every field as opaque text. Most of the label taxonomy is optional and additive. Three labels are not: title, url, and iconUrl must all be applied to schema properties, or the content will not surface in Copilot at all (it may still appear in Microsoft Search). These three are gates, not best practices. Among them, title is the highest-impact label — it drives the result-cluster experience and is currently the only label usable directly in Copilot prompts.

The minimal Copilot-correct schema, then, is the three mandatory labels plus isSearchable: true on the title property so prompts can match against it:

{
  "baseType": "microsoft.graph.externalItem",
  "properties": [
    {
      "name": "ticketTitle",
      "type": "String",
      "isSearchable": true,      // the property user prompts match against — required for grounding
      "isRetrievable": true,
      "labels": ["title"]        // mandatory Copilot label
    },
    {
      "name": "ticketUrl",
      "type": "String",
      "isRetrievable": true,
      "labels": ["url"]          // mandatory Copilot label
    },
    {
      "name": "ticketIcon",
      "type": "String",
      "isRetrievable": true,
      "labels": ["iconUrl"]      // mandatory Copilot label
    }
  ]
}

Beyond the three, the label taxonomy is broad, and applying the ones that fit your data improves discoverability and ranking.

Each label maps to exactly one property, and a labeled property must be retrievable and carry a matching data type. The enum also includes a unknownFutureValue sentinel that marks the list as one Microsoft continues to extend — treat it as a placeholder and never assign it.

💡 Insight: Apply every applicable label at schema-creation time. The schema cannot be updated once items are ingested, so a label you skip today means recreating the schema and reingesting later. Front-loading the labels is cheaper than the redo.

What this means for you: treat title, url, and iconUrl as a hard checklist before you ingest a single item — and add every other label that fits while the schema is still editable.

Access Control: How External Groups Map Source Permissions to Microsoft 365 Users

Every externalItem carries an acl array, and that array is the mechanism by which Microsoft 365 Copilot and Microsoft Search enforce permission trimming. Neither surface returns an item to a user the ACL does not permit — regardless of how the user phrases the query — and trimming happens at query time, so there is no window in which unauthorized content leaks into a Copilot answer.

Each ACL entry has four fields. type is one of user, group, everyone, everyoneExceptGuests, or externalGroup. value is the identifier — an Entra object ID, an external group ID, or one of the broad-access keywords. accessType is grant or deny. identitySource is azureActiveDirectory for Entra users and groups, or External for non-Entra groups. One rule governs conflicts: a deny entry overrides a grant entry — if any deny rule matches a user, they are denied even when a grant rule also matches.

The externalGroup resource is what lets a connector honor permissions that live only in the source system. When access is governed by a ServiceNow local group or a Salesforce permission set — groups that have no Entra representation — you define the group and its membership through the externalGroup API, then reference it from an item’s ACL with type: "externalGroup" and identitySource: "External". That maps the source-system membership onto Microsoft 365 users without replicating the groups into Entra ID. The simplest ACL, by contrast, is a single-user grant: one entry with type: "user", the user’s Entra object ID as value, and accessType: "grant" — the form the ingestion example in the next section uses.

What this means for you: mirror the source system’s permission model in the item ACL from the first ingestion — an over-permissive ACL surfaces content in Copilot to users who should never have seen it in the source.

Building a Custom Synced Connector: The Four-Step Lifecycle

Building a custom synced connector is a four-step sequence against the Copilot connectors API. Every call is application-only — there is no delegated-permission variant and no signed-in-user context for ingestion. The auth model itself is the standard Microsoft Graph app-registration flow covered in Post 02; this section assumes it and focuses on the connector specifics.

Step 1 — Register the app and grant application permissions.
Create a Microsoft Entra ID app registration and grant the connector permissions, then obtain tenant admin consent (application permissions always require it). Use the least-privileged OwnedBy pair unless you must manage connections your app does not own.

Step 2 — Create the external connection.
POST the container. A 201 Created returns the connection object.

POST https://graph.microsoft.com/v1.0/external/connections
Content-Type: application/json
{
  "id": "contosohr",
  "name": "Contoso HR",
  "description": "Connection to index Contoso HR tickets and knowledge"
}

Step 3 — Register the schema (long-running operation).
PUT the schema with the three mandatory labels and isSearchable on the title property. This is asynchronous: the call returns 202 Accepted with an Operation-Location header. Poll that header until the operation reports completed — items cannot be ingested until schema provisioning finishes.

PUT https://graph.microsoft.com/v1.0/external/connections/contosohr/schema
Content-Type: application/json
{
  "baseType": "microsoft.graph.externalItem",
  "properties": [
    { "name": "ticketTitle", "type": "String", "isSearchable": true, "isRetrievable": true, "labels": ["title"] },
    { "name": "ticketUrl",   "type": "String", "isRetrievable": true, "labels": ["url"] },
    { "name": "ticketIcon",  "type": "String", "isRetrievable": true, "labels": ["iconUrl"] }
  ]
}

Step 4 — Ingest items.
Once the schema is completed, PUT each item by ID with its ACL, properties, and content.

PUT https://graph.microsoft.com/v1.0/external/connections/contosohr/items/ticket123
Content-Type: application/json
{
  "acl": [
    {
      "type": "user",
      "value": "e811976d-83df-4cbd-8b9b-5215b18aa874",
      "accessType": "grant"
    }
  ],
  "properties": {
    "ticketTitle": "Error in the payment gateway",
    "ticketUrl": "https://hr.contoso.com/tickets/123",
    "ticketIcon": "https://hr.contoso.com/favicon.ico"
  },
  "content": {
    "value": "Full description of the payment gateway error and its resolution...",
    "type": "html"
  }
}

Once the connection exists, you can check its state through the externalConnection resource. This post does not enumerate the connection-state values, because they must be read from the current API reference rather than assumed — consult the externalConnection resource reference for the full list of states and what each means operationally.

✅ Quick win: Prove the pipeline with the minimum viable configuration first — the three mandatory labels, one searchable property, and a single test item with a simple grant ACL. Confirm that item appears in Microsoft Search before you add more properties or turn on Copilot inline results. A schema that provisions to completed and an item that shows in Search is the fastest signal that the plumbing is correct.

What this means for you: gate item ingestion on the schema reaching completed — ingesting against an unfinished schema is the most common self-inflicted failure in a first build.

What Copilot Actually Requires to Surface Connector Content — and the Admin Step That Is Easy to Forget

A healthy connection with indexed items is necessary but not sufficient for Copilot. Four conditions must all hold before connector content appears in a Copilot response:

1. The three semantic labels are applied. iconUrl, title, and url must all be on the schema. Miss any one and the content will not surface in Copilot, even though it may still appear in Microsoft Search.

2. isSearchable: true is set on the content properties. This is the single most important schema attribute for Copilot grounding — it defines which properties a user prompt can match against. Without it, ingested content is never retrieved for grounding.

3. An admin has enabled inline results for the connection. In the Microsoft 365 admin center: Search & Intelligence > Customizations > Verticals > All vertical > Manage connector result, then select Show results inline and check the connection. This is a manual step the indexing pipeline does not perform for you.

4. The requesting user is in the item’s ACL. Permission trimming is enforced at query time; Copilot never cites an item the user cannot access.

Note: The inline-results admin step is required even when the connection is healthy and every item is indexed. Skip it and the connector is invisible to Copilot Chat — no error, no warning, just no results. This is the single most common reason a correctly built connector produces nothing in Copilot.

Beyond the four gates, several practices improve grounding quality without being mandatory. Ingest content-rich HTML or text in content — Copilot performs better on substantial items than on thin ones. Adding a urlToItemResolver in the connection’s activitySettings is strongly recommended (though not required): it lets Copilot recognize when users share URLs from your source, and items shared with a user are more likely to be surfaced for them. Recording externalActivity entries on items boosts their ranking, and a meaningful connection description — what the content is, how users refer to it, when they use it — measurably helps the model decide when to reach for the connector.

In the resulting Copilot Chat experience, connector results arrive with a source citation and a short summary, so users get the answer without opening the source system; multiturn conversations stay in context and can draw on several connectors at once. The experience is read-only by default — Copilot cannot write back to the source through a connector unless it is extended with action-oriented connectors or plugins.

What this means for you: treat the four conditions as a single unit — three of them live in your schema, but the fourth lives in the admin center, and a deployment that verifies only the code half will ship a connector that never answers.

What Microsoft Has Already Built: Synced Connectors (GA) and Federated Connectors (Preview)

Before building anything custom, check what Microsoft already ships. Microsoft builds and maintains over 100 connectors, split into synced (largely GA) and federated (largely preview) categories. A representative — not exhaustive — sample of the synced, GA set: Confluence Cloud and On-premises, ServiceNow (Tickets, Knowledge, Catalog), Salesforce (CRM, Knowledge), Jira (Cloud, Data Center), GitHub, Azure DevOps (Wiki, Work Items), Google Drive, Amazon S3, Azure SQL and Microsoft SQL Server, on-premises SharePoint Server, Windows file shares, Dropbox, Gong, and Zoom Meetings. On-premises sources — file shares, on-premises SQL, on-premises SharePoint Server — additionally require the Microsoft Graph connector agent, a lightweight Windows service installed on a machine that can reach the source.

The federated set is newer and, in the gallery today, almost entirely under a preview label: Salesforce CRM (federated variant), HubSpot, Box, Notion, Google Calendar, financial-data sources such as FactSet and S&P Global, Harvey, Tableau Cloud, and Zendesk Ticket, among others.

⚠️ Preview: Federated connectors in the gallery are, at the time of writing, almost all marked “(preview),” and some synced connectors are too. To deploy a connector marked “(preview),” enable the Targeted release option for your admin account. Treat preview connectors as subject to change and validate them outside production before you depend on them.

Because GA-versus-preview status varies connector by connector and the gallery is updated frequently, check the current gallery listing for your specific target system rather than assuming its connector is GA.

What this means for you: search the gallery for your source system before scoping a custom build — a prebuilt connector, even a preview one, is almost always less work than building and maintaining your own.

Licensing, Limits, and Quotas: What Your Tenant Needs Before Connector Grounding Works

The licensing gate decides which connector experiences a tenant can actually use, and it is where connector projects most often stall late. Base Microsoft 365 unlocks Microsoft Search over synced connector content but not Copilot grounding and not federated connectors. Copilot grounding and federated access require the Microsoft 365 Copilot add-on or Microsoft 365 E7.

Two notes carry consequences. Indexing synced connector data incurs no extra cost for tenants with Microsoft 365 licenses, and where the tenant already holds Copilot licenses, connector grounding in Copilot is included. But federated connectors require the Copilot add-on or E7 for every user who queries the federated source — Copilot Studio licenses and pay-as-you-go do not qualify. Confirm the assignment model for your procurement before committing to a federated rollout.

The API also enforces hard limits worth designing against from the start.

On capacity, the default item quota is 5 million items per connection, raisable to 50 million on request at aka.ms/GraphConnectorsHigherCapacity. The published limits cover item counts; they do not document a separate crawl-frequency or crawl-rate quota. If your source is large or changes rapidly and crawl cadence matters, consult the manage-connector documentation for crawl scheduling and any rate limits on crawl operations rather than assuming the item quota is the only ceiling.

What this means for you: verify the tenant’s license tier against this table before you build — a connector indexes fine on base Microsoft 365 and still returns nothing in Copilot, because grounding is the line the license draws.

Connector vs. Retrieval API: Complementary Tools for Different Integration Directions

Connectors and the Retrieval API (Post 06) point in opposite directions and are easy to confuse. A connector brings external data into the Microsoft 365 semantic index, making it available tenant-wide through Microsoft Search and Copilot grounding without any developer-built query layer — any permitted user can find it in Copilot Chat. The Retrieval API is a developer-facing Graph endpoint that programmatically retrieves content already in the Microsoft 365 index from inside a custom application. They are complementary: use a connector to ingest external content into the index, then optionally use the Retrieval API to query that content from your own app. The Retrieval API cannot ingest anything — it only retrieves — so it is never a substitute for a connector.

What this means for you: if your goal is to get external data discoverable in Copilot, you need a connector; if your goal is to query indexed content from your own app, you need the Retrieval API — and a full solution often needs both.

Seven Checks Before Your Connector Appears in Copilot Responses

Consolidate every gate from this post into one pre-go-live pass. Most failures here surface as silence — indexed content that never appears — not as a runtime error, so this checklist, not the logs, is what catches them.

• License verified: the tenant has the M365 Copilot add-on or E7 for Copilot grounding; federated-connector users each hold the same.
• App permissions consented: the app registration holds ExternalConnection.ReadWrite.OwnedBy + ExternalItem.ReadWrite.OwnedBy (minimum) with tenant admin consent granted.
• Mandatory labels present: the schema applies all three of iconUrl, title, and url, with isSearchable: true on at least the title-labeled property.
• Schema provisioned: the Operation-Location poll reports completed before any item ingestion begins.
• ACLs correct: every item’s ACL has at least one grant entry, and any deny entries are intentional — deny overrides grant.
• Inline results enabled: an admin has turned on Show results inline for this connection in Search & Intelligence.
• Preview handled: for a federated or preview connector, confirm the connector is deployable — Targeted release is active on the admin account.

What this means for you: run this checklist after your first successful item ingestion and before announcing the connector is live — most connector failures produce no error, only an absence of results.

Now What? Your Next Three Steps

1. Check the Copilot connectors gallery for your target source — confirm whether a prebuilt synced or federated connector already exists before you scope a custom build; a preview connector still beats maintaining your own.

2. Register a minimal schema and validate it provisions — start with only the three mandatory labels (iconUrl, title, url) and one searchable property, and confirm the Operation-Location poll reaches completed before adding complexity.

3. Enable inline results after first ingestion — open Search & Intelligence > Customizations > Verticals in the Microsoft 365 admin center and turn on Show results inline for the connection; without this step the connector is invisible to Copilot Chat.

How to Navigate This Series

This series runs 13 posts across 3 phases, moving from API landscape and governance foundations through the core Copilot API surfaces into agent architecture and extensibility.

• Phase 1 — Foundations and Governance (Posts 01–04): API landscape (Post 01), auth and permissions (Post 02), rate limits and national cloud readiness (Post 03), and usage reporting (Post 04).
• Phase 2 — Building with Core APIs (Posts 05–09): Package Management API (Post 05), Retrieval API (Post 06), Chat API (Post 07), Meeting AI Insights (Post 08), and AI Interactions Change Notifications (Post 09).
• Phase 3 — Agents and Extensibility (Posts 10–13): this post on Copilot connectors, declarative versus custom engine agents (Post 11), Copilot Studio (Post 12), and SPFx and enterprise integration patterns (Post 13).

By role:

• Architects choosing an integration path: → Post 01 → Post 06 → Post 10 → Post 11
• Developers building a custom connector: → Post 02 → Post 06 → Post 10
• M365 admins evaluating connectors: → Post 01 → Post 10 → Post 12

This post sits at the opening of Phase 3 and establishes the connector surface that the agent layer consumes. For the application-permission and admin-consent patterns behind the ExternalConnection and ExternalItem scopes used here, see Post 02. For the retrieve-from-the-index counterpart that this post contrasts against, see Post 06. Readers who plan to reference connector data inside a Copilot Studio agent will find that path in Post 12.

The immediate next post is Post 11 — Declarative Agents vs. Custom Engine Agents, which covers the agent taxonomy that determines how the connector knowledge you configure here is actually consumed.

References

All claims in this post trace to the following official Microsoft documentation:

• 1. Copilot connectors overview — synced versus federated, licensing, how Copilot uses connector data — https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/overview
• 2. Microsoft 365 Copilot connector experiences — mandatory Copilot labels, inline-results admin step, Search configuration — https://learn.microsoft.com/en-us/graph/connecting-external-content-experiences
• 3. Work with the Copilot connectors API — conceptual overview, four-step build lifecycle, resource types — https://learn.microsoft.com/en-us/graph/connecting-external-content-connectors-api-overview
• 4. Use the Copilot connectors API (Graph v1.0 reference) — GA confirmation, resource table, known limitations — https://learn.microsoft.com/en-us/graph/api/resources/connectors-api-overview?view=graph-rest-1.0
• 5. Copilot connectors API limits — 128 properties, 30 MB item size, activity and external-group limits — https://learn.microsoft.com/en-us/graph/connecting-external-content-api-limits
• 6. Prerequisites for deploying connectors — licensing table, admin roles, item quota (5M/50M) — https://learn.microsoft.com/en-us/microsoftsearch/licensing
• 7. Semantic label enum (v1.0) — full list of label members for schema properties — https://learn.microsoft.com/en-us/graph/api/resources/externalconnectors-schema
• 8. Manage schema — semantic labels, label impact order, one-property-per-label rule — https://learn.microsoft.com/en-us/graph/connecting-external-content-manage-schema
• 9. Use external groups to manage permissions — externalGroup API, non-Entra ACLs, identitySource External — https://learn.microsoft.com/en-us/graph/connecting-external-content-external-groups
• 10. Microsoft-built connectors gallery — synced and federated connectors, preview labels — https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/connectors-gallery-microsoft
• 11. Copilot connectors versus Power Platform connectors — architectural distinction and use-case guidance — https://learn.microsoft.com/en-us/microsoft-copilot-studio/knowledge-graph-vs-power-platform-connectors
• 12. Create, update, and delete items in a connection — externalItem shape, ACL structure, content types — https://learn.microsoft.com/en-us/graph/connecting-external-content-manage-items
• 13. Microsoft Graph permissions reference — ExternalConnection.ReadWrite.OwnedBy, ExternalItem.ReadWrite.OwnedBy, Directory.Read.All — https://learn.microsoft.com/en-us/graph/permissions-reference