Build custom apps using Peakon REST API

In addition to the existing supported integrations, Peakon exposes an external REST API, allowing you to build custom applications.

The JSON-based REST API can be utilised to build integrations that leverage results from your engagement surveys, thus extending the power of Peakon even further.

The REST API goes beyond data provisioning to enable users to programmatically access resources otherwise only exposed via the Peakon dashboard.

Documentation

The most important step prior to creating your custom application is to confirm that all resources needed by your application are being exposed via the API. The API documentation describes all endpoints and provides a simple interface to test each one out. 

Getting started

For the remainder of this article, we are going to present a step-by-step guide on how to create a simple custom application sending requests to one of the engagement endpoints. 

If you are already familiar with web development with RESTful APIs, you might want to go straight to the API documentation page instead.

Step-by-step guide for your first application

Note that this guide covers solely how to integrate any given application with Peakon, it is not a comprehensive list of all pertinent tasks of application development.

Create a custom app with proper permissions

The very first step when creating a new application is to manually register it in the Custom Apps page (see screenshot below). When creating the application, note that the application must have a unique name within the company. 

More importantly, at this point you will be requested to select which permissions to give your application. Typically, each permission grants the application access to a particular subset of the API, thus exposing different aspects of the company. That said, we consider it to be best practice to grant minimum access to your application.

In this example, we are going to create a simple application to retrieve the engagement overview for a given hypothetical company.

Get and store your application token

Once you have decided on a name and set of permissions for your application, you can hit the "Create custom app" button. As a result, a modal dialog pops up with a unique access token for your application. 

Important to note: this token is the only credential used by your application to access remote resources in Peakon. Therefore, treat it as a secret, keep it safe, and do not share between two different applications. 

Because of the sensitivity of this token, it will be displayed only once.

Authenticating your application

Once you have manually created a token for your application, it's the application's responsibility to get itself authenticated before sending any HTTP request out to the API.

The authentication step is accomplished by sending an HTTP POST request to the /v1/auth/application endpoint (see screenshot below). In response to a successful authentication request, a Json Web Token is returned and all subsequent API requests must contain an Authorization header bearing the encoded token. 

Note that the separation of authentication and authorization tokens enables a deployment scenario where only an application developer or a company admin has access to the authentication token, while authorization tokens are assigned and shared with application users.

In other words, for any given application, it can be authenticated more than once concurrently. This way you can track and manage different installations of one given application within your company.

Sending a request to the API

It is now time to illustrate a request sent to the engagement overview endpoint, more specifically an HTTP GET request to /v1/engagement/overview (see screenshot below).

Remember as mentioned, the request must carry an Authorization header with a bearer token returned by the /v1/auth/application endpoint (see above). If you click the red-highlighted lock icon, a modal dialog pops up allowing a bearer token to be typed in.

Optionally, one can send a request with additional parameters, for example; filtering out data or specifying a specific time interval. Please refer to the documentation page for more detailed information on each parameter.