Skip to main content
Nederlands
Nederlands

REST API

 

Introduction

The platform's RESTful API allows you to exchange data between the platform and external systems. You can retrieve, add, update or remove data — for example to publish messages automatically or to manage events from another system.

In this article you will learn how the RESTful API works, how to view the API documentation through Swagger, how authentication works and what to do if you run into problems.

Please note:
Using the API requires technical knowledge of REST and data modelling. Correct use of the API and the management of the related data is always the customer's responsibility.

 

How does the RESTful API work?

The RESTful API supports four types of requests, each with a clear purpose:

  • GET: retrieve data from the platform.
  • POST: add new data to the platform.
  • PATCH: update existing data.
  • DELETE: remove data.

The full set of available requests is documented automatically through Swagger. Swagger is a tool that generates an interactive documentation page based on the API itself, where you can also try requests directly.

 

What data can you access through the API?

The API exposes a range of data, including:

  • User information
  • Documents
  • Messages
  • Group information
  • Events

This makes it possible, for example, to publish or remove messages automatically at scheduled times, or to plan and update events from another system.

 

Open the API documentation through Swagger

Once the api-docs page is available on your platform, you can open it in your browser to view and test every available request.

  1. Go to your platform URL (for example https://my.plek.co).
  2. Add /api-docs to the URL, so it looks like this: https://my.plek.co/api-docs.

  3. The Swagger documentation page opens and shows every available request, grouped by topic.

    Swagger documentation page showing an overview of available API requests

  4. Expand a request and click Try it out to run it directly from the page.
Tip:
Use Swagger to try out requests before adding them to a production integration. You will immediately see which parameters are required and what response to expect.

 

Authentication with client-ID and client-Secret

Every API request must include authentication details. Without valid authentication, the request will be rejected.

The authentication details consist of two values:

  • Client-ID: a unique identifier for your platform.
  • Client-Secret: a unique API key that acts as the password.

Both values are configured in the main configuration on the platform VHost. An administrator with the right permissions can create and manage these credentials.

Warning:
Treat your client-Secret like a password. Never share it publicly (for example in code repositories or chat messages) and store it only in a secure location. If you suspect it has been exposed, request new credentials immediately.

 

Troubleshooting

My request returns a 401 or 403 error

  • Check that the client-ID and client-Secret are sent correctly in the request header.
  • Check that the credentials are still active in the platform's main configuration.
  • Check that the user you are working with has sufficient permissions for the requested data.

The /api-docs page does not load

  • Check that you are using the correct VHost URL (no typos in the domain).
  • Check that the api-docs page has been activated on your platform. Contact support if you are unsure.

My POST or PATCH request is rejected

  • Check that the request body matches the expected data model (see the Swagger documentation).
  • Check that all required fields are included.
  • Try the request through Swagger first to see the exact error message.

I have lost my client-Secret

A client-Secret cannot be retrieved again after it is created. Send an email to support.plek@bcs-hr.com to have a new one generated. Contact support as well if the issue persists after going through the steps above.