Tom Talks Microsoft Teams and Microsoft 365 news and opinions

Microsoft Teams PSTN Call Records Log / Bill from Microsoft Graph API

A long asked for API feature, the ability to pragmatically collect the PSTN call records and charges from Microsoft Teams, e.g. the phone bill. Up until now, you have only been able to get this by exporting it from the Teams Admin Center into Excel, but now, in beta, you can collect these records from Microsoft Graph.

It forms part of the call records API. The Microsoft docs for the API call: callRecord: getPstnCalls

You can expect to see lots of call reporting/bill generation products to use this API to collect this information for billing. Many large organisations cross charge their telephony costs by country or department.

This is something Modality Systems (who I work for) have been doing for some time in a somewhat bespoke way for large enterprises by automating the export of the the excel report from the Teams Admin Center (basically making automated website calls) into SQL then into Power BI. Still, the API will provide a much more robust and supportable method to export the data from Microsoft.

APIs under /beta in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported, but hopefully, this will come out of beta too. I will update the blog when it is out of beta.

This will cover any PSTN call scenarios

  • Microsoft PSTN Audio Conferencing
  • Microsoft Calling Plans
  • Microsoft Communications Credits
  • Microsoft Call Queues and Auto Attendants (the PSTN legs)
  • Direct Routing (though with no charges/costs since that information is not held by Microsoft)

Lee Ford at Symity was very fast in producing a PowerShell script to collect the call records from the API. You can check out his work here. Thanks Lee!



The API will give you the following for each record:

pstnCallLogRow resource type

Property Type Description
id String Unique call identifier. GUID.
callId String Call identifier. Not guaranteed to be unique.
userId String Calling user’s ID in Graph. GUID. This and other user info will be null/empty for bot

call types (ucap_in, ucap_out).

userPrincipalName String UserPrincipalName (sign-in name) in Azure Active Directory. This is usually the same as the user’s SIP Address and can be same as the user’s e-mail address.
userDisplayName String Display name of the user.
startDateTime DateTimeOffset Call start time.
endDateTime DateTimeOffset Call end time.
duration Int32 How long the call was connected, in seconds.
charge Double Amount of money or cost of the call that is charged to your account.
callType String Whether the call was a PSTN outbound or inbound call and the type of call such as a

call placed by a user or an audio conference.

currency String Type of currency used to calculate the cost of the call (ISO 4217).
calleeNumber String The number dialed in E.164 format.
usageCountryCode String Country code of the user, ISO 3166-1


tenantCountryCode String Country code of the tenant, ISO 3166-1


connectionCharge Double Connection fee price.
callerNumber String Number that received the call for inbound calls or the number dialed for outbound

calls. E.164 format.

destinationContext String Whether the call was domestic (within a country or region) or international (outside a

country or region) based on the user’s location.

destinationName String Country or region dialed.
conferenceId String ID of the audio conference.
licenseCapability String The license used for the call.
inventoryType String User’s phone number type, such as a service of toll-free number.

About the author

Tom Arbuthnot

A Microsoft MVP and Microsoft Certified Master, Tom Arbuthnot is Principal Solutions Architect at Microsoft Collaboration specialists Modality Systems.

Tom stays up to date with industry developments and shares news and his opinions on his blog, Microsoft Teams Podcast and email list. He is a regular speaker at events around the world.


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Tom Talks Microsoft Teams and Microsoft 365 news and opinions