Microsoft Teams Data API

Microsoft Corporation · Communication

Microsoft Teams is Microsoft Corporation's workplace chat and meetings app for Microsoft 365 organizations and the successor to Skype for Business. Its left rail lists the teams and channels a user belongs to, with favorites, unread markers, @-mention counts and a preview of the latest message, and 1:1 chats, group chats and channel threads open into one conversation view with a compose box. A people picker searches the company directory, colored presence dots show whether a colleague is available, busy or on Do Not Disturb alongside a status note and whether they are working in the office or remotely, and users can pin their own availability from the phone until a chosen expiry time. The Meetings tab lists the day's calendar with RSVP status, organizer and a one-tap join button for online meetings, while the Me tab holds the user's profile, job title and contact details. Features are gated by Microsoft 365 licensing, from the free tier and trials through small-business plans and Copilot add-ons, and information-barrier policies let regulated organizations stop designated groups from chatting with each other. Teams competes with Slack and Google Chat in workplace messaging and with Zoom in video meetings, and is used every day by enterprises, small businesses and schools in the United States, India and Brazil to run internal communication.

Tenant-scoped identity records keyed by an mri tie the whole dataset together: the me profile and people search return userPrincipalName, displayName, jobTitle, department, companyName and tenantId, plus emailsInfo and phonesInfo entries that carry their own visibility and searchable flags, while chat and channel rosters add the information-barrier flag isIbBarred and isBlocked. Presence lookups layer availability, activity, lastSeenAt, a status note and the hybrid workLocation (location, subLocation) onto each member, and avatar resolution returns an imageUri or an avatarHint when no photo is set.

Conversation data pages out per thread: each message carries content, composetime, from, imdisplayname and clientmessageid, and the team and channel list adds channelType, isFavorite, mentionCount, lastMessageArrivalTime and a previewMessage. The calendar view returns each event's Subject, Start, End, Organizer, ResponseStatus, IsOnlineMeeting and OnlineMeetingUrl; license reads return skuPartNumber with per-plan provisioningStatus, and the account's license details mark its tier with isFreemium, isTrial, isCopilot and isTeamsSmb.

Teams-aware tooling builds on these fields: nightly jobs upsert mri, userPrincipalName, jobTitle and tenantId into an HRIS or ITSM so leavers and role changes show up the next morning; service desks paint live availability and workLocation next to each ticket owner so agents know who is in a call before they @-mention; on-call dashboards deep-link responders into the current meeting through OnlineMeetingUrl; and records pipelines archive message threads for eDiscovery. openData Studio turns this Teams data into callable open data.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Read the signed-in user's me profile

GET /v1/profile/me?expand=identityFlags osint

Returns the signed-in user's identity record (mri, UPN, job title, tenant, email/phone visibility) that the Me tab and every other signed-in call hang off.

Auth: OAuth2 Bearer access token for the signed-in work account (directory/profile scope). The optional expand query returns the account's identity flags alongside the profile.

mri
objectId
displayName
givenName
surname
email
mail
userPrincipalName
jobTitle
department
companyName
tenantId
tenantName
userType
isSkypeTeamsUser
skypeTeamsInfo
emailsInfo
address
searchable
visibility
phonesInfo
number
country
nationalNumber
riskScore
searchableByProfile

GET /v1/profile/me?expand=identityFlags HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "mri": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
  "objectId": "3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
  "displayName": "Alex Rivera",
  "givenName": "Alex",
  "surname": "Rivera",
  "email": "[email protected]",
  "mail": "[email protected]",
  "userPrincipalName": "[email protected]",
  "jobTitle": "Product Manager",
  "department": "Platform",
  "companyName": "Example Corp",
  "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
  "tenantName": "Example Corp",
  "userType": "Member",
  "isSkypeTeamsUser": true,
  "skypeTeamsInfo": {"isSkypeTeamsUser": true},
  "emailsInfo": [{"address": "[email protected]", "searchable": true, "visibility": "Everyone"}],
  "phonesInfo": [{"number": "+14255550123", "country": "US", "nationalNumber": "4255550123", "searchable": false, "visibility": "Contacts"}],
  "riskScore": "0",
  "searchableByProfile": true
}

Search the org directory for people

POST /v1/directory/people:search?expand=identityFlags osint

Runs the in-app people picker / search-results directory lookup and returns matching user records (mri, UPN, jobTitle, tenantId, identity flags).

Auth: OAuth2 Bearer access token for the signed-in work account (directory scope).

value
mri
objectId
displayName
email
userPrincipalName
jobTitle
department
tenantId
type
userType
isSkypeTeamsUser
imageUri
skypeTeamsInfo

POST /v1/directory/people:search?expand=identityFlags HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

"alex rivera"

{
  "value": [
    {
      "mri": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
      "objectId": "3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
      "displayName": "Alex Rivera",
      "email": "[email protected]",
      "userPrincipalName": "[email protected]",
      "jobTitle": "Product Manager",
      "department": "Platform",
      "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
      "type": "Member",
      "userType": "Member",
      "isSkypeTeamsUser": true,
      "imageUri": "https://example.invalid/avatar/alex",
      "skypeTeamsInfo": {"isSkypeTeamsUser": true}
    }
  ]
}

Batch-fetch user profiles by member id

POST /v1/directory/people:batchGet osint

Hydrates a roster of chat/channel members from a list of member ids into full user records, including information-barrier barred flags.

Auth: OAuth2 Bearer access token for the signed-in work account (directory scope).

mri
objectId
displayName
email
userPrincipalName
jobTitle
tenantId
isIbBarred
isBlocked
userType
skypeTeamsInfo
isSkypeTeamsUser
value

POST /v1/directory/people:batchGet HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

[
  "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
  "8:orgid:9c88e201-4b77-41aa-b012-55aa11cc99ee"
]

{
  "value": [
    {
      "mri": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
      "objectId": "3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
      "displayName": "Alex Rivera",
      "email": "[email protected]",
      "userPrincipalName": "[email protected]",
      "jobTitle": "Product Manager",
      "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
      "isIbBarred": false,
      "isBlocked": false,
      "userType": "Member",
      "skypeTeamsInfo": {"isSkypeTeamsUser": true}
    }
  ]
}

Batch-lookup presence for users

POST /v1/presence:batchLookup osint

Returns presence, status note, hybrid work location and any forced availability for a batch of member ids, powering the green/yellow/red dots on chat and people lists.

Auth: OAuth2 Bearer access token for the presence service. Body is a list of {mri, eTag} pairs so unchanged entries can be skipped.

mri
eTag
userMri
availability
activity
capabilities
lastSeenAt
note
mRawStatusMessage
mStatusExpiry
mStatusPublishTime
workLocation
location
subLocation
locationExpiry
locationForced
forcedAvailability
mAvailability
mActivity
mExpiry
mPublishTime

POST /v1/presence:batchLookup HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

[
  {"mri": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33", "eTag": "W/\"datetime'2026-09-27T10:00:00Z'\""},
  {"mri": "8:orgid:9c88e201-4b77-41aa-b012-55aa11cc99ee", "eTag": ""}
]

[
  {
    "userMri": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
    "availability": "Available",
    "activity": "Available",
    "capabilities": "Audio|Video|ScreenShare",
    "eTag": "W/\"datetime'2026-09-27T10:04:12Z'\"",
    "lastSeenAt": "2026-09-27T10:04:12Z",
    "note": {
      "mRawStatusMessage": "In a customer call",
      "mStatusExpiry": "2026-09-27T18:00:00Z",
      "mStatusPublishTime": "2026-09-27T09:00:00Z"
    },
    "workLocation": {
      "location": "Office",
      "subLocation": "Building 34",
      "locationExpiry": "2026-09-27T23:59:59Z",
      "locationForced": false
    },
    "forcedAvailability": {
      "mAvailability": "Busy",
      "mActivity": "InACall",
      "mExpiry": "2026-09-27T11:00:00Z",
      "mPublishTime": "2026-09-27T10:00:00Z"
    }
  }
]

Publish a forced availability status

PUT /v1/presence/me/override opendata

Publishes the signed-in user's forced presence (Available/Busy/DoNotDisturb and activity) from the mobile device until the requested expiry time.

Auth: OAuth2 Bearer access token for the presence service.

id
deviceType
availability
activity
desiredExpirationTime

PUT /v1/presence/me/override HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "id": "Mobile",
  "deviceType": "Mobile",
  "availability": "Busy",
  "activity": "InACall",
  "desiredExpirationTime": "2026-09-27T11:00:00Z"
}

{
  "id": "Mobile",
  "deviceType": "Mobile",
  "availability": "Busy",
  "activity": "InACall",
  "desiredExpirationTime": "2026-09-27T11:00:00Z"
}

Page messages in a chat or channel thread

GET /v1/messaging/threads/{threadId}/messages opendata

Pages the message history of a 1:1 chat, group chat or channel thread for the conversation view, including compose time, sender id and consumption horizon.

Auth: Chat-scoped session token sent as a token header (minted by the session-token endpoint), plus the device registration token issued when the chat endpoint registers.

threadId
view
startTime
pageSize
messages
id
clientmessageid
conversationid
from
imdisplayname
messagetype
contenttype
content
composetime
originalarrivaltime
properties
consumptionHorizon
forwardLink

GET /v1/messaging/threads/19:[email protected]/messages?view=msnp24Equivalent&startTime=0&pageSize=50 HTTP/1.1
Authorization: sessionToken <session-token>
RegistrationToken: registrationToken=<registration-token>
Accept: application/json

{
  "messages": [
    {
      "id": "1758962400123",
      "clientmessageid": "18446744073709550001",
      "conversationid": "19:[email protected]",
      "from": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
      "imdisplayname": "Alex Rivera",
      "messagetype": "RichText/Html",
      "contenttype": "text",
      "content": "<p>Standup notes are in the wiki.</p>",
      "composetime": "2026-09-27T10:00:00.123Z",
      "originalarrivaltime": "2026-09-27T10:00:00.200Z",
      "properties": {
        "consumptionHorizon": "1758962400123;1758962400123;1758962400000"
      }
    }
  ],
  "_metadata": {
    "forwardLink": "/v1/messaging/threads/19:[email protected]/messages?syncState=abc"
  }
}

Send a message to a chat or channel thread

POST /v1/messaging/threads/{threadId}/messages opendata

Posts a new chat or channel message from the compose box and returns the server-assigned id, arrival time and echoed body.

Auth: Chat-scoped session token sent as a token header, plus the device registration token for the registered chat endpoint.

content
contenttype
messagetype
clientmessageid
imdisplayname
OriginalArrivalTime
id
conversationid
from
composetime

POST /v1/messaging/threads/19:[email protected]/messages HTTP/1.1
Authorization: sessionToken <session-token>
RegistrationToken: registrationToken=<registration-token>
Content-Type: application/json

{
  "content": "<p>Shipping the build at 16:00.</p>",
  "contenttype": "text",
  "messagetype": "RichText/Html",
  "clientmessageid": "18446744073709550002",
  "imdisplayname": "Alex Rivera"
}

{
  "OriginalArrivalTime": "2026-09-27T10:05:01.004Z",
  "id": "1758962701004",
  "clientmessageid": "18446744073709550002",
  "conversationid": "19:[email protected]",
  "from": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
  "imdisplayname": "Alex Rivera",
  "messagetype": "RichText/Html",
  "contenttype": "text",
  "content": "<p>Shipping the build at 16:00.</p>",
  "composetime": "2026-09-27T10:05:00.980Z"
}

List the signed-in user's calendar view

GET /v1/calendar/me/view opendata

Returns the day's calendar events for the Meetings tab, including subject, window, RSVP, organizer and the online-meeting join URL.

Auth: OAuth2 Bearer access token (calendar scope). The window is passed as startDateTime and endDateTime.

startDateTime
endDateTime
Id
Start
End
iCalUId
Subject
Type
SeriesMasterId
Locations
IsAllDay
IsOnlineMeeting
IsCancelled
OnlineMeeting
OnlineMeetingUrl
ResponseStatus
Organizer
OriginalStartTimeZone
Recurrence
DateTime
TimeZone
JoinUrl
DisplayName
EmailAddress
Name
Address
Response
Time

GET /v1/calendar/me/view?startDateTime=2026-09-27T00:00:00Z&endDateTime=2026-09-28T00:00:00Z&$select=Id,Start,End,iCalUId,Subject,Type,SeriesMasterId,Locations,IsAllDay,IsOnlineMeeting,IsCancelled,OnlineMeeting,OnlineMeetingUrl,ResponseStatus,Organizer,OriginalStartTimeZone,Recurrence HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "value": [
    {
      "Id": "AAMkAGI2AAAt2j2NAAA=",
      "iCalUId": "040000008200E00074C5B7101A82E00800000000A0A0A0A0",
      "Subject": "Platform standup",
      "Type": "SingleInstance",
      "SeriesMasterId": null,
      "Start": {"DateTime": "2026-09-27T15:00:00.0000000", "TimeZone": "UTC"},
      "End": {"DateTime": "2026-09-27T15:30:00.0000000", "TimeZone": "UTC"},
      "Locations": [{"DisplayName": "Teams meeting"}],
      "IsAllDay": false,
      "IsOnlineMeeting": true,
      "IsCancelled": false,
      "OnlineMeetingUrl": "https://meetings.example.invalid/join/19%3ameeting_abc123",
      "OnlineMeeting": {"JoinUrl": "https://meetings.example.invalid/join/19%3ameeting_abc123"},
      "ResponseStatus": {"Response": "Accepted", "Time": "2026-09-26T18:01:00Z"},
      "Organizer": {"EmailAddress": {"Name": "Alex Rivera", "Address": "[email protected]"}},
      "OriginalStartTimeZone": "Pacific Standard Time",
      "Recurrence": null
    }
  ]
}

List the signed-in user's teams and channels

GET /v1/workspaces/me/summary opendata

Returns the optimized left-rail list of teams and channels for the signed-in user, including favorite flags, unread/mention counts and the last-message preview.

Auth: OAuth2 Bearer access token (workspace aggregation scope).

conversations
conversationId
parentConversationId
displayName
conversationType
channelType
tenantId
isFavorite
isUnread
mentionCount
consumptionHorizon
lastMessageId
lastMessageArrivalTime
previewMessage

GET /v1/workspaces/me/summary HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "conversations": [
    {
      "conversationId": "19:[email protected]",
      "parentConversationId": null,
      "displayName": "Platform",
      "conversationType": "Team",
      "channelType": null,
      "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
      "isFavorite": true,
      "isUnread": true,
      "mentionCount": 2,
      "consumptionHorizon": "1758962400123;1758962400123;1758962400000",
      "lastMessageId": 1758962400123,
      "lastMessageArrivalTime": 1758962400123,
      "previewMessage": "Standup notes are in the wiki."
    },
    {
      "conversationId": "19:[email protected]",
      "parentConversationId": "19:[email protected]",
      "displayName": "General",
      "conversationType": "Channel",
      "channelType": "Standard",
      "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
      "isFavorite": true,
      "isUnread": true,
      "mentionCount": 0,
      "consumptionHorizon": "1758962400123;1758962400123;1758962400000",
      "lastMessageId": 1758962400123,
      "lastMessageArrivalTime": 1758962400123,
      "previewMessage": "Standup notes are in the wiki."
    }
  ]
}

Read the account's license SKUs

GET /v1/account/me/licenses opendata

Returns the signed-in user's assigned subscription SKUs and service plans (including the meetings/chat plan) used to gate licensed features.

Auth: OAuth2 Bearer access token with the organization user-read scope.

id
skuId
skuPartNumber
servicePlans
servicePlanId
provisioningStatus
value

GET /v1/account/me/licenses HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "value": [
    {
      "id": "c7890e12-aaaa-4bbb-8ccc-0123456789ab",
      "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900",
      "skuPartNumber": "ENTERPRISEPACK",
      "servicePlans": [
        {
          "servicePlanId": "57ff2da0-89d1-429b-9cd3-4d0f0c7d0a1e",
          "provisioningStatus": "Success"
        }
      ]
    }
  ]
}

Exchange the account token for a chat session token

GET /v1/auth/sessionToken opendata

Exchanges the account-level OAuth2 token for the chat-scoped session token, member id and regional routing info that every chat-service call (messages, long-poll, presence docs) requires.

Auth: OAuth2 Bearer access token for the app's auth service. The returned tokens.skypeToken is then sent as the Authorization token header on chat-service calls.

tokens
skypeToken
expiresIn
tokenType
mri
skypeId
region
partition
regionOverride
userInfo
cid
primaryMemberName
skypeName
licenseDetails
isFreemium
isTrial
isCopilot
isAdvComms
isTeamsSmb

GET /v1/auth/sessionToken HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "tokens": {
    "skypeToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400,
    "tokenType": "skype"
  },
  "mri": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
  "skypeId": "orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
  "region": "amer",
  "partition": "amer",
  "regionOverride": null,
  "userInfo": {
    "cid": 0,
    "primaryMemberName": "[email protected]",
    "skypeName": "orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33"
  },
  "licenseDetails": {
    "isFreemium": false,
    "isTrial": false,
    "isCopilot": false,
    "isAdvComms": false,
    "isTeamsSmb": false
  }
}

Batch-resolve profile pictures

GET /v1/directory/people/avatars osint

Batch-resolves avatar imageUri values for the chat list and people cards from member id + displayName, including an avatarHint when the user has no photo.

Auth: OAuth2 Bearer access token for the signed-in work account (directory scope). usersInfo is a compact encoding of member-id + displayName pairs.

usersInfo
mri
displayName
imageUri
avatarHint
etag
value

GET /v1/directory/people/avatars?usersInfo=%5B%7B%22mri%22%3A%228%3Aorgid%3A3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33%22%2C%22displayName%22%3A%22Alex%20Rivera%22%7D%5D HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "value": [
    {
      "mri": "8:orgid:3f2a1c90-9b11-4d2e-a7c4-0f8e6b1d2a33",
      "displayName": "Alex Rivera",
      "imageUri": "https://example.invalid/avatar/alex",
      "avatarHint": "ProfilePicture",
      "etag": "W/\"datetime'2026-08-01T12:00:00Z'\""
    }
  ]
}

Data categories

profiles
directory
presence
messages
calendar
licenses
avatars

Where teams use this data

Org-directory reconciliation
Nightly jobs pull the me-profile and people-search endpoints (mri, userPrincipalName, jobTitle, tenantId) and upsert them into an HRIS or ITSM so leavers and role changes show up in Teams-aware tooling the next morning.
Live presence overlay on a helpdesk
A service desk posts MRI batches to the presence batch-lookup endpoint and paints availability, activity, lastSeenAt and workLocation next to each ticket owner so agents know who is in a call before they @-mention.
Meeting-join from an ops console
On-call dashboards read the calendar-view endpoint for Id, Subject, Start, End, IsOnlineMeeting and OnlineMeetingUrl, then deep-link responders into the current Teams meeting without opening the calendar tab.
Chat-thread compliance export
After minting a chat-scoped session token, a records pipeline pages the thread-messages endpoint (content, composetime, from, imdisplayname, clientmessageid) into an archive for eDiscovery.

Frequently asked questions

Which identity fields does the Teams me profile return?

The me-profile call returns mri, objectId, displayName, givenName, surname, email, userPrincipalName, jobTitle, department, companyName, tenantId, tenantName, emailsInfo, phonesInfo and identity flags.

How does Teams authenticate chat versus directory calls?

Directory, calendar and license calls send an OAuth2 Bearer token. Chat calls first exchange that account token for a chat-scoped session token, then send the session token as a token header plus a device registration token when paging or posting thread messages.

What presence attributes can you read for a colleague?

The presence batch-lookup call returns availability, activity, capabilities, lastSeenAt, a status note, hybrid workLocation (location, subLocation) and any forced availability window.

Where do Teams meeting join URLs come from?

The Meetings tab loads the calendar-view endpoint. Each event carries Id, iCalUId, Subject, Start, End, IsOnlineMeeting, OnlineMeetingUrl and Organizer.

Apps similar to Microsoft Teams

Slack — Channel-based team messaging with a mature app ecosystem and powerful search; the free plan keeps a 90-day message history.
Zoom Workplace — A video-first workspace whose AI Companion generates meeting summaries and action items, with team chat and whiteboarding alongside meetings.
Google Chat — Google's team messaging app, with deep native integration into Docs, Sheets, Drive and Calendar for organizations built on Google Workspace.
Cisco Webex — An enterprise suite for meetings, calling and messaging aimed at large organizations, including those with existing Cisco infrastructure.
RingCentral — Combines cloud PBX calling, video meetings and team messaging in a single unified communications system.
Discord — Real-time voice, video and text chat organized around community servers, also used by some teams for work communication.
Mattermost — A self-hosted team messaging platform aimed at organizations that need compliance and control over their data.
Rocket.Chat — An open-source messaging platform that can be fully self-hosted and extensively customized.

More Communication apps

MTS Link
Communication · 14 endpoints

Topics

microsoft teams api
teams chat messages
teams presence api
teams people search
teams calendar view
teams session token
mri userPrincipalName
teams licenseDetails

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote