Developer DiscussionDeveloper BlogAtlas
Guides

Care Reporting API development kit

Suggest Edits

The following article provides a set of tested examples against which an actual application can be built. The examples below reference the Khoros API library for Care data reporting. They also reference cURL, a commonly available API development tool.

API development resources

To obtain cURL Packages (Wizard, for Executable), select here.

📘

Note

You can also use alternatives, such as Postman. However, testing of actual downloads might not work, as Postman presently lacks a direct mechanism to follow the redirects.

Useful tools

Care APIs use Epoch Time as a standard. To view the Epoch time converter, select here.

Typical cURL installation for development

Location: Unpack the above in a suitable location, for example C:/CURL>.

cURL tests can then be run by switching to C:\CURL> and executing commands like this, using the filename option if required for download:

curl –options –user(auth info):report_url –o

Sample Reports

Below are sample Analytics reports generated via the Care API. These examples use cURL as a test and development tool; you can use Postman and other third-party REST tools just as easily.

Example 1: Generate a report of Current Conversations

Call
Use quotation marks around URL if it contains special characters.

curl --user [email protected]:password "https://API_ENDPOINT/api/public/reports/report/conversation?conversationReportType=OPEN_AT_END&startTime=1470614400000&endTime=1461104100000&timezoneOffset=-18000000&reportFormat=csv&locale=en_US&companyKey=sitekey"

If you do not use quotation marks, the call fails.

curl --user [email protected]:password https://API_ENDPOINT/api/public/reports/report/conversation?conversationReportType=OPEN_AT_END&startTime=1458508500000&endTime=1461104100000&timezoneOffset=-18000000&reportFormat=csv&locale=en_US&companyKey=sitekey

Response

{"status":"PASS","request":null,"message":null,"result":{"workflowId":"fc2990ad-4798-3628-a794-8a2ee2ce0da1","runId":"23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ=","downloadUrl":"https://API_ENDPOINT/api/public/reports/report/fc2990ad-4798-3628-a794-8a2ee2ce0da1/23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ%3D/download?companyKey=sitekey","statusUrl":"https://API_ENDPOINT/api/public/reports/report/fc2990ad-4798-3628-a794-8a2ee2ce0da1/23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ%3D/status?companyKey=sitekey"}}

Note that the above response generates two URLs:

  • The first URL can be queried, with the return of “CLOSED/SUCCESS” as indication that the download file containing the data is ready for download. For large reports, the report compile time might take several hours.
  • This second URL is that URL at which the report is located. It is useful to apply the –L (follow redirects) cURL option, and as well to apply the –o (specify output file name) for convenience.

Report status call

Following the initial call, the next step is to query the reporting API to establish whether or not the report has been completed. Lengthy reports can take time to run: the recommended polling interval is 30 seconds.

curl --user [email protected]:password "https://API_ENDPOINT/api/public/reports/report/fc2990ad-4798-3628-a794-8a2ee2ce0da1/23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ%3D/status?companyKey=sitekey"

Status call response

{"status":"PASS","request":null,"message":null,"result":{"jobInfo":{"workflowId":"fc2990ad-4798-3628-a794-8a2ee2ce0da1","runId":"23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ=","downloadUrl":"https://API_ENDPOINT/api/publi
c/reports/report/fc2990ad-4798-3628-a794-8a2ee2ce0da1/23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ%3D/download?companyKey=sitekey","statusUrl":"https://API_ENDPOINT/api/public/reports/report/fc2990ad-4798-3628-a794-8a2ee2
ce0da1/23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ%3D/status?companyKey=daveesb"},"result":{"runnerState":"CLOSED","detail":"COMPLETED"}}}

Report download call

Finally, having received the "COMPLETED" confirmation and the download URL, you can obtain the report. The format is CSV, following the spec for the report requested.

curl -L --user [email protected]:password "https://API_ENDPOINT/api/public/reports/report/fc2990ad-4798-3628-a794-8a2ee2ce0da1/23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ%3D/download?companyKey=sitekey"

Download response

"Conversation ID","Conversation Work Queue","Conversation Priority","Status","Created Date","Closed Date","Assignee","Conversation Source","Source Tags","Language Tags","Location Tags","System Tags","All Custom Tags","Authors","Author Handles","All Author Tags","Sentiment Conversion","# of Positive Posts","# of Neutral Posts","# of Negative Posts","Total Incoming Posts","Total Responses","Total Private Incoming Posts","Total Private Responses","Response Handles Used","Author Responded","LSW Conversation Link","Average Response Handle Time (min)","Average Response Approval Handle Time (min)","Assigned Agent Conversation Handle Time (min)","Conversation Handle Time - Wrap Up Time (min)","Total Conversation Handle Time (min)","# of Auto Tags","Auto Tags","# of Manual Tags","Manual Tags"

"2886627","Amazon AppStore","3","Closed - Resolved","01/06/2016 00:51:16 AM","06/30/2016 02:19:36 PM","LI-API_USER","Rss","Source>Forum>App Store","Language>English","","Language>English, Source>Forum>App Store","","By AzzTek","By AzzTek","","","0","0","0","1","0","0","0","","N/A","https://name.response.lithium.com/console/agent/2886627","0","0","0","0","0","2","Language>English, Source>Forum>App Store","0",""

Send report directly to local file

To send the report directly to a local file, use the following format when requesting:

curl -L --user [email protected]:password "https://API_ENDPOINT/api/public/reports/report/fc2990ad-4798-3628-a794-8a2ee2ce0da1/23PkrBpRGvcH8X2ckxmX0gsoh92m9YtMbewFuaJIZ5HxQ%3D/download?companyKey=sitekey" -o report.csv

Response

% Tot% Rec’d% XfrdAvg SpdTimeTimeTimeCurrentDloadUploadTotalSpentLeftSpeed
00000:00:010:00:010:00:012034710020347113220:00:010:00:0165214

See local file “report.csv” for full reported data.

Updated about 2 months ago