Official Product Name

Product

Title	DataExport for TDRs

URL Name	DataExport-for-TDRs

Overview

The DataExport API is used to provide Sky customers with access to TDRs (Talk Data Records) through a web service rather than through the Account Portal user interface. This allows for two key items that expands on TDR Reporting through the Portal:

Bulk reporting (e.g., extracting TDRs for all calls over a 2-week span) is not available through the Portal.
Customers and partners cannot build applications to automatically log into the Portal and extract TDR reports at regular intervals.

The DataExport web service not only allows for bulk reporting (returning raw data over an arbitrary time span), but also allows for programmable access to this data, making it simple to script automatic report requests into customer and partner applications.

NOTE: The Sky phone system also provides a CDR Data Export API scripting feature that enables customers to extract CDR (Call Detail Record) data generated by their account. For more information, see the CDR Data Export article.

Use

Reports can be generated by making an HTTP request to our DataExport service. The request must include authentication information and report parameters. (See the tables below.)

Individual TDRs are defined as a single row of data containing the data listed in the section below. The report is returned as plain text in a CSV (comma-separated values) format, including column headings, with each value contained in double quotes (ex. "Subscriber","Subscriber Label","Date","Time","Call Direction", etc.)

Authentication is performed by transmitting the User and Password parameters in the initial HTTP request headers via HTTP POST.

If a web browser is being used to pull a report, the Account Portal will prompt for a username and password after the HTTP request is received.
If the request is being made via programming, the POST headers should include the username and password with the original request. (See the "wget" code in the Example of Use section below.)

Other parameters are passed via an HTTP request that is appended to the requested URL. Individual parameters should be separated with an ampersand (&).

Limitations

The following are limitations associated with using the DataExport for TDRs API:

Maximum number of requests to the API per day is 24 (data is updated approximately every one to three hours).
TDR data is retained for 25 months.

Please note that the data does not change after it is written so there is no benefit to downloading the same data more than once. Multiple downloads of the same data may cause the maximum number of requests to be exceeded.

Description of Returned Data

Column Name	Description
Subscriber	The DID of the profile from whose perspective the TDR is interpreted (NPANXXxxxx format - e.g. 3215551234)
Subscriber Label	The name of the profile associated with the TDR
Date	The date on which the call was initiated (mm/dd/yyyy format, UTC)
Time	The time at which a call was initiated (hh:mm:ss, 24-hour UTC)
Call Direction	Inbound, Outbound, Internal, or Forward. Provides the direction of a given call record. Inbound and Outbound indicate whether the subscriber placed or received the call. Internal indicates calls within an account. Forward indicates calls that were transferred.
Remote Party TN	The non-subscriber end of the call. For outbound calls, this is the dialed DID. For inbound calls, this is the source DID. (NPANXXxxxx format - e.g. 3215551234)
Remote Party Label	The label of the non-subscriber participant. For outbound calls, this is taken from the Subscriber's directory. For inbound calls, it is taken from CNAM (Caller ID). For internal calls, it is the name of the other profile. Note that this field is empty if directory/CNAM info is unavailable.
Dialed TN	The DID to which the call was actually placed. Only populated for inbound calls when the Subscriber was not the DID dialed (for example, calls to toll free numbers or ring groups). (NPANXXxxxx format - e.g. 3215551234)
Dialed Label	The label of the component associated with the DID to which the call was originally placed. Since this only occurs on answered inbound calls, this is populated whenever Dialed TN is present.
Ring Time	Time, in seconds, that the Subscriber's phone rang before the call was answered.
Talk Time	Time, in seconds, that the Subscriber participated in this leg of the call.

Mandatory Parameters

Parameter	Description
startDate=	Various formats are supported, as long as they parse to C# datetime type. Supports specifying time part. All times are treated as UTC, and time zone offsets are not supported. If no time is specified, 12:00AM UTC is assumed.
endDate=	Various formats are supported, as long as they parse to C# datetime type. Supports specifying time part. All times are treated as UTC, and time zone offsets are not supported. If no time is specified, 12:00AM UTC is assumed.

Optional Parameters

Parameter	Description
subscribers=	Any 10 digit telephone number that belongs to the account. Multiple numbers can be specified in a comma separated list. If not specified, returns all telephone numbers. (NPANXXxxxx format - e.g. 3215551234)
remoteTN=	Any 10 digit incoming telephone number. Not supported for CDRs. Note that in case of TDRs this might be less than 10 digits and in case of CDRs it is actually 11 digits. If not specified, returns all telephone numbers. (NPANXXxxxx format - e.g. 3215551234)
connected=	Options are: yes, no, and all (this would allow the user to include only live calls, non-live calls or all calls). Supported only for TDRs. Defaults to "Yes".
accountId=	Used to show call data for a different account than the one that the authenticating user belongs to. Requires proper permissions set on the server side. Defaults to the account of the authenticating user.
direction=	Options are: inbound, outbound or forward. The forward option is not applicable to CDRs. By default, all directions are shown.

Requesting Access

For an Existing Account Contact

A Decision Maker may submit a Support request to gain access to the DataExport API. If you are requesting that access be added to an existing authorized contact, your request may look like this:

Please grant me permissions to access the DataExport API. I would like to run Talk Time Reports on my account without using the Account Portal interface.

Since you should already have the username and password, Support will simply confirm that these permissions have been added for you.

For a new Account Contact

If you'd like specific user credentials created for reporting, or if you would like to grant a partner or other third party, such as a CRM developer, access to your call records, your request may look like this:

Please create a user on my account named @ and grant it permissions to access your DataExport API. I would like to have access to my call data.

In this case, Support should provide you with the new username, the password, and your Account Portal Account ID. If you would like Support to send these credentials directly to a third party, please specify who should receive them in your request.

Example of Use

$ wget --user=user@ringcentral .com --password=pass "https://portal.shoretelsky.com/DataExport/TDRData?startDate=2012-02-01&endDate=2012-03-01&direction=inbound&connected=true&subscribers=6464425780,6464421610"

This results in the following response:

HTTP request sent, awaiting response... 401 Unauthorized
Connecting to portal.shoretelsky.com ... connected.
HTTP request sent, awaiting response... 200 OK
Length: 1389 (1.4K) [text/csv]
Saving to: `TDRData@startDate=2012-02-01&endDate=2012-03-01&direction=inbound&connected=true&subscribers=6464425780,6464421610'

100%[====================================================================================================================>] 1,389 --.-K/s in 0s

2012-02-24 12:10:25 (11.6 MB/s) - `TDRData@startDate=2012-02-01&endDate=2012-03-?
01&direction=inbound&connected=true&subscribers=6464425780,6464421610' saved [1389/1389]

FAQ

Q: Can DataExport reporting be limited to an individual location?
A: No, reports run through DataExport are account-wide. Location information is not included in the report. The scope of a report can be limited by DID (see the Subscriber and RemoteTN parameters above).

Q: How wide a date range can I report on?
A: The further back your report goes, the longer the query will take to complete, and reports over longer time spans can get large very quickly. If you are doing regularly scheduled reporting, we recommend pulling at 24-hour intervals (no longer than a week).

Q: How current is the TDR data?
A: The data is refreshed at a minimum of once every two hours following the completion of a call (and as frequently as once every 15 minutes). See the following FAQ for a more detailed explanation.

Q: How soon are calls available via DataExport reporting?
A: This depends on a number of factors. Most importantly, a call must complete before it is available via TDR reporting. Since calls are reported based on start time, a long call can cause some unexpected behavior. For example, a report that is run each hour for the previous hour's calls will completely miss a call that lasts 2 hours because the report containing the start time of the call has already been processed. In addition, there is some processing overhead associated with multiple call legs which can cause a slight delay in availability. If accuracy in reporting is a strict requirement, it is safer to factor in some delay and report over a slightly longer time span (for example, wait until 8 PM to run a report on activity that occurred from 12 PM to 4 PM). A common way to avoid this for non-24x7 customers is to run reports overnight for the previous day's activity.

Q: Do I have to use wget to pull these reports?
A: No - we chose wget for our example because it's free, simple, well-documented, and widely available. You can use any method that you choose to submit an HTTP request for a report (including PHP/curl, methods from any major programming language, or even a simple web browser).

Known Issues

Reports downloaded using the DataExport API may truncate data at the end of international calls.

DataExport for TDRs

Table of Contents

Use