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 alpha-2.
tenantCountryCode	String	Country code of the tenant, ISO 3166-1 alpha-2.
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.