API documentation and endpoints - an introduction

In this article we want to guide you through a topic that keeps coming up in the babelforce world: APIs. This topic might seem intimidating at first but don't worry, we'll have it explained as easy as it gets.

Firstly, what is an API?

API is the abbreviation for application programming interface. These application programming interfaces are a standardized method that enables communication between different software components and even external providers if they are granted access.

And what are they useful for?

By means of our API endpoints you can get all babelforce related data that you can access via our manager and much more. They are especially useful to extract our babelforce metrics data for instance.

If you do not have a tool to work with APIs yet, we recommend you using the Postman app. You can download it here: https://www.getpostman.com/downloads/

Once you downloaded the tool, you can start exploring:

Request types:

Depending on the type of endpoint request you use, you can carry out different actions. The most important request types are the following:

mceclip0.png

A GET request will show you information depending on the endpoint you requested. By means of a PUT request you can change existing data. A POST request will add something competely new. And with a DELETE request you can, delete data. This could for example be a custom busy status you don't need any longer, or an agent. We recommend you starting to play around with the GET requests first. You cannot damage anything and they are the most important for our purposes anyway.

 

Setting up a new endpoint:

Now, let's have a look at how you set up a new endpoint.

mceclip3.png

Therefore, go to the upper left corner, and click on collections > new collection. Name it "babelforce" for instance.

Click on your new collection and add your first request. Name it "wrap-up" time:

 

 

 

mceclip0.png

mceclip1.png

Great, now you can open the endpoint. For each of the endpoints we use, we have to make sure that an authorization exists, which allows us to carry out the request. There are several authentication methods available to use in Postman. We'll guide you through the easiest one:

API authentification:

For this authentication method we have to head over to the babelforce manager app first. Click on your email address on the top right corner and go to the overview section. There you find a so called accessId and an accessToken.

mceclip1.pngNow, we have to tell the endpoint to use the accessId and accessToken for the authorization. Therefore we go to "Headers" and put in these strings in like shown in the screenshot:

mceclip0.png

Next, let's have a look at our basic babelforce API URL:
https://{{environment}}.babelforce.com/api/v2/

Unless you are working on a babelforce custom environment, you can simply replace the {{environment}} placeholder by "services", like this:
https://services.babelforce.com/api/v2/

If you are working on a custom environment, type in that one, instead of "services".

Note, that this is only one way to authorize your API endpoint. If you start working more intensely with our API, you should have a look at this page for instance, which explains the topic more detailed.

Great, now we just have to fill in our endpoint in the field which says "enter request URL". Let's take the average wrap-up time:

https://services.babelforce.com/api/v2/metrics/wrapup/avg

Click on send and let's have a look at the result:

The most important information is the "value". It is the average wrap-up time displayed in milliseconds. Furthermore you find some information about the time range and the runtime (the time needed to make the request).

{
  "id": "queues.wrapup.avg",
  "type": "avg",
  "metric": {
    "value": 12156.48
  },
  "request": {
    "id": "queues.wrapup.avg",
    "runtime": 7,
    "cachable": true,
    "timeRange": {
      "from": "2019-11-07T00:00:00.000Z",
      "to": "2019-11-07T19:03:02.999Z",
      "value": "TODAY",
      "duration": 68582999
    }
  },
  "success": true
}

We hope we could give you a first insight into the work with APIs. Of course, you have so many more possibilities. It is for example possible to download the results or to adjust single parameters of a request like the time range for instance. However, we recommend you to have a closer look at our API documentation for some deeper insight. If you are using Postman, you can download our entire API collection with one click without having to build all the endpoints by yourself.

Now that you gathered a first insight into the world of APIs, you can go ahead and explore it yourself. Have fun!

Have more questions? Submit a request