Getting Started With the Work IQ API in Microsoft 365 Copilot

Most of the agents businesses ask us to build fail for a boring reason. They do not know who they are talking to. You build something clever on top of a language model, it answers general questions well, and then someone asks "what did I agree to in the meeting with the Brisbane team on Tuesday" and it has nothing. The model is smart. It just has no idea about your work.

Work IQ is Microsoft's answer to that gap, and the Work IQ API is how you get at it from your own code. If you have been building declarative agents or custom engine agents and hitting the wall where they feel generic, this is the piece that changes the feel of the thing. Microsoft's Work IQ API quickstart walks through the first call. What I want to do here is explain what you are actually plugging into, where it earns its keep, and the setup steps that quietly eat an afternoon if you go in cold.

What Work IQ actually is

Strip away the branding and Work IQ is the reasoning layer that sits over a person's working context inside Microsoft 365. Their emails, their meetings, the files they touch, the people they work with, the sense of what is recent and what matters. It is the same substrate that makes Copilot in Word or Teams feel like it knows your world rather than answering from a blank slate.

For a long time that context was locked inside Microsoft's own products. You could use Copilot, but you could not build on the intelligence underneath it in a first-class way. The Work IQ API opens that up. You send a conversation request, and the response comes back grounded in the signed-in user's work context, with the same permissions and boundaries they already have. If a user cannot see a file in SharePoint, Work IQ will not surface it to your agent either. That last part matters more than it sounds, and I will come back to it.

The mental model I give clients is this. A raw model call is a very well-read graduate who started this morning and knows nothing about your company. A Work IQ call is that same graduate after they have read your inbox, sat in your meetings, and met your team, but only the parts you are allowed to show them. The intelligence is the same. The context is the whole difference.

Where this is worth reaching for

Not every agent needs Work IQ, and I would rather say that plainly than sell it as the answer to everything. If you are building a public-facing chatbot that answers product questions, this is not your tool. Work IQ is about the individual's work life, so it shines when the job is personal and internal.

The cases where it has paid off for the teams we work with tend to look like this. A morning briefing agent that pulls together what is coming up, who you owe replies to, and what changed while you were asleep. An assistant that drafts a reply grounded in the actual thread history and the related documents, not a generic template. A "catch me up" agent for someone coming back from leave who has four hundred unread emails and a fortnight of meetings to reconstruct. In each of those, the value is not the model being clever. It is the model knowing the specific mess of one person's work.

That is squarely the territory our AI agent builders spend their days in, and the honest lesson from those projects is that grounding beats cleverness almost every time. A simpler agent with real context out-performs a sophisticated one working blind, and users can feel the difference in the first thirty seconds.

The setup that actually takes the time

The quickstart makes the first call look like three lines, and once everything is in place it more or less is. Getting everything in place is the part worth planning for.

First, permissions. The Work IQ API runs on Microsoft Graph style consent, which means your app registration needs the right scopes and, in most tenants, an admin has to approve them. This is not a technicality you can wave through. In a lot of Australian organisations, especially anyone in financial services or health, the person who can grant tenant-wide consent is not the person writing the code, and they will want to know exactly what the app can see before they click approve. Line that conversation up early. I have watched more than one prototype sit finished for two weeks waiting on a consent approval nobody had asked for.

Second, licensing. Work IQ is tied to Microsoft 365 Copilot licensing, so the users your agent serves generally need to be licensed for Copilot. It is easy to build and test against your own licensed account, ship it, and then discover half the intended audience does not have the licence and gets nothing back. Check the licensing reality of your actual user base before you promise anyone a rollout date.

Third, authentication flow. Work IQ operates on behalf of a signed-in user, so you are working with delegated access, not an app-only service credential quietly running in the background. Your app authenticates the user, gets a token carrying their identity, and every call is scoped to what that user can see. If you have built app-only Graph integrations before, this is a different shape and it is worth being clear about from the start. You cannot have a nightly batch job reach into Work IQ as "the service" and pull everyone's context. It follows a person.

That constraint frustrates people at first, and then they realise it is the whole point. The permission model is inherited, not reinvented. You are not building a new security surface that some future audit will pick apart. You are riding on the one Microsoft 365 already enforces, and that is a much easier story to tell your risk team. It is the sort of thing we end up walking clients through in our Microsoft AI consulting work, because the governance questions land well before the code does.

Making the first call

Once consent and auth are sorted, the actual interaction is refreshingly plain. You create a conversation, then send a chat message into it, and you get back a response grounded in the user's context. There is a streaming variant too, chat over stream, which you will want for anything user-facing because waiting several seconds for a full response to appear in one lump feels broken to people now, even when it is technically fast.

A worked pattern that holds up in production looks roughly like: authenticate the user and acquire a delegated token, create a conversation to hold the exchange, send the user's question as a chat message, and render the streamed response as it arrives. The conversation object gives you continuity, so follow-up questions keep the thread rather than starting cold each time. That continuity is doing quiet work. "Summarise that" only means anything if the thing you are talking to remembers what "that" was.

My advice for the first build is to resist the urge to wire it straight into a slick interface. Get it answering in a console or a bare test rig first, prove the grounding is real by asking questions only your own work context could answer, and confirm the permission boundaries behave. Only then put a face on it. The failure mode I see is teams building the pretty part first and discovering the grounding is thinner than they assumed once they finally test with someone else's account.

The honest caveats

A few things worth going in clear-eyed about, because the quickstart understandably shows the happy path.

Some of the Work IQ surface carries preview labels, and preview means the shape can shift and the terms of use are their own thing to read rather than skim. Fine for building and piloting. I would think twice before putting a preview surface at the centre of something a whole business depends on until it is generally available, and I would tell a client the same.

Latency is real. You are not just calling a model, you are calling a model that first has to reason over a person's work context, and that takes longer than a bare completion. Design for it. Stream the response, show that something is happening, and do not build interactions that assume an instant reply.

And grounding is not magic. Work IQ surfaces what is genuinely there and reachable, so if a user's Microsoft 365 house is a mess, with important decisions buried in chat messages nobody can find and documents scattered across a dozen sites, the agent inherits that mess. It reflects the state of the underlying data. This is often the more valuable conversation to have anyway. Sometimes the real fix is not a smarter agent, it is sorting out where the organisation actually keeps its knowledge, and that is a strategy question as much as a technical one. It is exactly the kind of thing our business AI work exists to untangle before a line of agent code gets written.

Where I would start

If you are weighing this up, do the smallest honest test first. Register an app, get the delegated permissions consented in a dev tenant, and make one grounded call against your own account. Ask it something only your real work context could answer. When it comes back knowing about your actual meeting from yesterday rather than a plausible guess, you will understand immediately why this is different from bolting a chatbot onto a search box.

From there the build is mostly ordinary application work: auth, a bit of state, a decent interface, and clear thinking about which user problem you are actually solving. The Work IQ part, once the setup is behind you, is the straightforward bit.

If you are trying to work out whether a Work IQ grounded agent is the right shape for a problem in your business, or you have a prototype that answers well in a demo but you are not sure how to get it safely in front of real users, get in touch. It is the kind of thing we can usually give you a clear read on quickly.