Executing a Report

❗️
The Reporting API has been replaced by the Explore API. Talkdesk strongly encourages the transition to the Explore API. You may still use the Reporting API, but please note:

Talkdesk will only provide support (no SLA for bug fixing or outage recovery) until June 1, 2022.

The Reporting API endpoint will stop responding to requests on December 1, 2022.

Request

Make a POST request to /reports/<report_type>/jobs

Parameters

🚧
These required parameters must be included in the body of the POST request.
Reports are aggregated by a record's end date/time. (i.e. Report on calls that ended between timespan.from: 2018-03-14 00:00:00 UTC and timespan.to: 2018-03-14 23:59:59 UTC).

Parameter	Description
format	Specifies the report’s format (JSON, CSV)
timespan.from	Specifies the start `datetime` filter for the records to be retrieved from the report. Depending on the report, this field will be mapped to a specific `datetime` field for that report.
timespan.to	Specifies the end datetime filter for the records to be retrieved from the report. Depending on the report, this field will be mapped to a specific datetime field for that report.

Sample Request

{
  "format": "INSERT_FORMAT_HERE",
  "timespan": {
    "from": "INSERT_FROM_DATETIME_HERE",
    "to": "INSERT_TO_DATETIME_HERE"
  }
}

Response

Request Response

If the request is successful, a 202 response with the parameters below is sent.

Parameter	Description
ID	Unique identifier of the reporting resource being created by the job
status	Job status: - Created (the job has been accepted and enqueued for processing). - Processing (the job is being processed). - Uploading (the result file is being uploaded). - Sending (the notification email is being sent). - Failed (the job failed during processing). - Done (the job was finalized successfully).
timespan.from	Start date-time filter specified for the report
timespan.to	End date time filter specified for the report
_links.self.href	Self-referenced URL to check the job status
_links.files.href	URL to access the report resource file once it has been created

Sample Response

{
  "id": "57add63204c799583700028e",
  "status": "created",
  "timespan": {
    "from": "2016-07-29 00:00:00 UTC",
    "to": "2016-07-29 23:59:59 UTC"
  },
  "_links": {
    "self": {
      "href": "https://api.talkdeskdev.com/reports/calls/jobs/57add63204c799583700028e"
    },
    "files": {
      "href": "https://api.talkdeskdev.com/reports/calls/files/57add63204c799583700028e"
    }
  }
}

🚧
Timespan Limits
The Reporting API does not provide access to real-time data. It strictly allows accessing historical call and agent status data and only requests with, at least, the timespan of an hour past the request or more will be allowed (e.g.: if the request is made at 2pm, a report for results generated at 1pm or after can't be requested).

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.