Use the Rest API below to get all users within your organization (tenant) and their associated information about Microsoft Teams.
NOTE: Please note these APIs are used by the PowerShell team and TAC. They could change any moment. They are not supported by Microsoft. They are not supported by me. Use at your own risk.
Get a list of users
To get a list of users in the organization. Each command uses the prefix https://api.interfaces.records.teams.microsoft.com/ to access the resource. Each command must include the Authorization and X-MS-Target-Uri header. For more information about each of these, please see Authentication to Teams Admin API. For additional details, you can see the Swagger page, but in my testing a lot of the results specified don’t work or return values. This page is to try to give you a real world look at how to use this endpoint.
GET: /Teams.User/users
The following is an example of a response.
{
"@nextLink": "",
"users": [
{
"accountEnabled": true,
"assignedPlans": [
{
"serviceInstance": "MicrosoftCommunicationsOnline",
"servicePlanId": "GUID",
"assignedTimestamp": "0001-01-01T00:00:00Z",
"capabilityStatus": "Enabled",
"capability": "MCOProfessional"
},
{
"serviceInstance": "exchange",
"servicePlanId": "GUID",
"assignedTimestamp": "0001-01-01T00:00:00Z",
"capabilityStatus": "Enabled",
"capability": "BPOS_S_Enterprise"
},
{
"serviceInstance": "TeamspaceAPI",
"servicePlanId": "GUID",
"assignedTimestamp": "0001-01-01T00:00:00Z",
"capabilityStatus": "Enabled",
"capability": "Teams"
},
{
"serviceInstance": "MicrosoftCommunicationsOnline",
"servicePlanId": "GUID",
"assignedTimestamp": "0001-01-01T00:00:00Z",
"capabilityStatus": "Enabled",
"capability": "MCOEV"
}
],
"dataProviderErrors": {},
"displayName": "Alice Anderson",
"objectId": "GUID",
"provisionedPlans": [
{
"capabilityStatus": "Enabled",
"provisioningStatus": "Success",
"service": "MicrosoftCommunicationsOnline"
},
{
"capabilityStatus": "Enabled",
"provisioningStatus": "Success",
"service": "MicrosoftCommunicationsOnline"
},
{
"capabilityStatus": "Enabled",
"provisioningStatus": "Success",
"service": "CRM"
},
...some removed for readability
],
"proxyAddresses": [
"SMTP:alice.anderson@domain.com",
"smtp:alice.anderson@domain.mail.onmicrosoft.com",
"smtp:alice.anderson@domain.onmicrosoft.com"
],
"sipAddress": "alice.anderson@domain.com",
"usageLocation": "US",
"userDirSyncEnabled": true,
"userPrincipalName": "alice.anderson@domain.com"
}
]
}
In the above response, you can see we get the basic information about each user. We can use the select and filtering commands below. Here is a sample of what it looks like from Insomnia.
Filtering, Select and Other Options
This endpoint supports the following options:
Filtering
Using standard OData filtering. See this Micorosft Graph Query Paramaters for some examples of OData filtering. These end points only support a small range of what can be used in MS Graph. Here are some working examples:
GET /Teams.User/users/?$filter=displayName eq 'Richard Brynteson'
Returns only records with the display name of Richard Brynteson
GET /Teams.User/users/?$filter=accountEnabled eq true
Returns only records where accountEnabled equals true
NOTE: OData requires the correct type of variable to be passed into it. For example, displayName is a string therefore you must pass a string wrapped in quotes. accountEnabled is a boolean so it must be true or false (lowercase). Do not wrap with quotes or it is a string and will fail.
Paging & Page Size
The API does support both page size and paging. Although there is something a bit strange with the page size function. If your request requires additional pages, you will be prompted with the @nextlink at the top of your return. You can then iterate on this link to get the next page size.
GET /Teams.User/users/?pagesize=50
A few items of note. First, there is no need to place a $ in front of pagesize. If you like OData, you can substitute the ?pagesize=15 for ?$top=15 for the same results. They appear to work the same. What is more interesting to me is that the number of results returned is not correct, ever. For example, if you pass 5 into page size, in all cases, I was returned with 3 results. Lastly, the max page size you can enter is 999. At 1000 or above, the endpoint will return an error.
To setup paging support, you do need to include the $skiptoken so you can jump between pages. Because the above pagesize does not appear to ever give the correct number of results, there is no need to create your own paging functionality.
Select
Using standard OData select statements, you can choose which items you would like to be returned in your request.
GET /Teams.User/users/?$select=displayName,accountEnabled
Returns only the selected fields. The result would look like:
{
"users": [
{
"accountEnabled": true,
"dataProviderErrors": {},
"displayName": "AA Assistance Voicemail"
},
{
"accountEnabled": false,
"dataProviderErrors": {},
"displayName": "Alice Ahlstrom"
}
]
}
The following fields may be included in the select command. I have tested each of these and know they work. There are other items listed in the sample response but many do not work.
- alias (string)
- accountEnabled (bool)
- assignedLicenses (object array)
- assignedPlans (object array)
- businessPhones (string array)
- callingLineIdentity (object array)
- conferencingPolicy (object array)
- dialPlan (string)
- enterpriseVoiceEnabled (bool)
- externalAccessPolicy (object array)
- featureTypes (string array)
- givenName (string)
- hideFromAddressLists (bool)
- hostingProvider (string)
- interpretedUserType (string)
- Will also include
- teamsUpgradeNotificationsEnabled (string)
- teamsUpgradePolicyIsReadOnly (string)
- isResourceAccount (bool)
- isSipEnabled (bool)
- licenseAssignmentStates (object array)
- lineUri (string)
- mail (string)
- mailNickName (string)
- objectId (GUID)
- onlineVoiceRoutingPolicy (object array)
- provisionedPlans (object array)
- proxyAddresses (string array)
- registrarPool (string)
- serviceInstance (string)
- shadowProxyAddresses (string array)
- sipAddress (string)
- sipProxyAddress (string)
- surname (string)
- tenantId (GUID)
- usageLocation (string)
- userDirSyncEnabled (bool)
- userPrincipalName (string)
- onPremEnterpriseVoiceEnabled (bool)
- onPremDomainName (string)
- onPremSecurityIdentifier (string)
- onPremSamAccountName (string)
- directoryStatus (string)
- pstnConnectivity (string)
- userValidationErrors (string array)
And the following Teams Policies. You must have a policy assigned otherwise the item does not even return in the response. No null, or blank.
- teamsMeetingPolicy
- teamsMeetingBroadcastPolicy
- teamsMessagingPolicy
- teamsCallParkPolicy
- teamsEmergencyCallingPolicy
- teamsEmergencyCallRoutingPolicy
- teamsCarrierEmergencyCallRoutingPolicy
- teamsChannelsPolicy
- teamsUpdateManagementPolicy
- teamsCallingPolicy
- teamsOwnersPolicy
- teamsTasksPolicy
- teamsUpgradePolicy
- teamsUpgradeOverridePolicy
- teamsAppSetupPolicy
- teamsAppPermissionPolicy
- teamsVerticalPackagePolicy
- teamsCallHoldPolicy
- dialoutPolicy
- teamsEnhancedEncryptionPolicy
- teamsFilesPolicy
Sorting
This endpoint does not support any OData sorting features.
