Overview
New API functionality was made available in version 4.2. Documentation on the API functionality can be found at guide.ximasoftware.com under the API section. This article is intended to show an example of how you can test your API queries. In this example, we'll test the Historical Data Access API functionality.
Please note that API use may not be for everyone and that some degree of Software Developer knowledge is commonly required to program API functionality. The tool we'll be using is called Postman, however please note that Xima Software does not develop or provide technical support for the Postman application. Postman is simply a free and easy to use application for testing purposes.
Lastly, Xima Support will not build customer API integrations. Considering the amount of third party customization that goes into an API integration, Xima Support's troubleshooting will be limited.
Create a Service User
Within Chronicall, create a new Service User. This will provide us with an authentication key.
- Create a new user in User Management > User Accounts.
- Click the User drop-down menu and select <New User>.
- Enter a name in the Name field and select the "Service User" option at the bottom.
- Save your changes.
Once completed, you will find the authentication key within API Enablement > Service Users.
Configure a Historical Data Access Report
Within Chronicall, we will configure a report to be used via the Historical Data Access API.
- Start by going to API Enablement > Historical Data Access.
- If this is your first API Report, it will take you directly to the configuration wizard. Otherwise, press Add.
- Select a report in the Report Template field. Any report available or created in the Chronicall Reports will be available for selection. In this example, we'll select the Agent Call Summary report.
- In the Service Account section, select the service account you created earlier.
- Note that a custom Report ID string was generated. This will be used later.
- Press OK. (don't skip this step)
Now the report has been enabled to be pulled via the API. However, we can further use the Chronicall API configuration wizard to help us format our API query.
- Re-open the report by going to API Enablement > Historical Data Access.
- If you have multiple reports, select the report that was just created and click Edit. Otherwise the report page may appear automatically.
- Click on Show Request Details
Here you will configure the report as though you were running it from the Reports section.
- In this example, we'll select the previous Monday (select a day that has data for best results).
- Also in this example, we'll select three Agents (again, select agents that will have data for best results).
- Lastly, in this example we'll select JSON as our Report Output.
- Press OK.
At this point, a page will open up with the details that would need to be sent in the API query to pull the requested report, the specified dates, the specified agents, and in the specified format. We will reference this information when we configure our query in Postman.
Download Postman
Download and install the Postman application at www.postman.com
Configure a Query
Launch Postman.
Create a new Request.
- We'll name the Request "API Demonstration".
- You may also need to create a "Collection". We'll call ours "Sample Collection".
Now that we have a request, we will first update the URL query.
- Change the API type to "POST".
- Copy the Target URL from the earlier API Request Details page in Chronicall and paste this in the Postman URL spot.
Next we'll configure the Authorization
- Within Postman, click the Authorization tab.
- Set the Type to Bearer Token.
- Copy the Service User Authentication Key and paste it here.
Next we'll configure the Header
- Within Postman, click the Headers tab
- Add "Content-Type" in the Key field
- Add "application/json" in the Value field
Lastly, we'll configure the Body
- Within Postman, click the Body field
- Among the options listed below, select raw
- Copy the Request Body Details from the earlier API Request Details page in Chronicall and paste this in the body field of Postman
We are now ready to submit our query. Click on Send within Postman. You will see the resulting response below in the Response field.
