sThis article explains how to use the vPlan API to import or read data or create an integration with an external application. This article is intended for a quick overview of all the possibilities and how to get started. The full technical documentation can be found at docs.api.vplan.com.

Overview

Wil je vPlan data gebruiken voor analytics, of vPlan connecten met een eigen app? Dan kun je gebruik maken van de vPlan API. vPlan's API biedt een middel voor software en scripts om informatie uit vPlan te lezen, informatie van buiten vPlan in te voeren en automatisch te reageren wanneer zaken veranderen. Dit kunnen zijn:

Want to use vPlan data for analytics, or connect vPlan to your own app? Then you can use the vPlan API. vPlan's API provides a means for software and scripts to read information from vPlan, input information from outside vPlan, and automatically react when things change. These can include:

Creating reports and dashboards on the status of your planning
Simultaneous synchronization with other ERP systems or accounting software, such as Exact Online or Moneybird, used in your organization
Adapt vPlan to your team's processes and workflows

Authentication

Any request to this API must always contain an Authorization Header unless otherwise specified. The vPlan API uses JWT as the authentication mechanism and the tokens are provided with OAuth 2.0.

JWT Token

A JWT (JSON Web Token) consists of three parts, a header, a payload and a signature. The signature is created on the server with a specific secret. A user cannot generate a JWT token himself. The header contains information about the token (type and signature algorithm). The payload contains information about the user and the validity of the token (username, expiration date, issuer). The signature is a hash generated with the defined algorithm in the header.

OAuth 2.0

OAuth is one of the most widely used methods for authentication. At its core, OAuth is a mechanism for applications to access the vPlan API based on a user, without the application having access to the username and password. Instead, applications are given a token. With this token, they can use proprietary application credentials to make API calls.

Tip

If you are not familiar with OAuth yet, take a moment to learn it here.

API key

API keys are only available in Trial, Basic and Professional packages of vPlan. If you need access to the vPlan API and you have admin rights in your account, you can create and view API keys:

In vPlan, go to Settings in the left menu bar, then click on Developers
If you haven't created an API key yet, click the plus icon next to the heading API keys.
Give your API key a name and click Save. A pop-up screen will appear showing your API key in full once. Copy the API key using the appropriate button and save it securely.
To delete an API key, you can always return to the Developers menu at a later time. In that menu click on the name of your API key and in the screen that follows click Delete.

Note

An API key is static and gives access to your entire vPlan database. We recommend changing your API key regularly. vPlan will automatically notify you once every six months.

Create an OAuth app

Technical information about OAuth can be found in our API documentation. The information below, is also explained in there, but from a technical point of view. Among other things, there you are referred to a technically simplified explanation.
In this article, we explain the following operations:

Registering an application
Connecting once
Repeating connection

Registering an application

Om via OAuth met vPlan verbinding te maken moet een developer zich eerst bekend maken bij vPlan.
To connect to vPlan via OAuth, a developer must first make themselves known to vPlan.

Go to https://developer.vplan.nl/
Click the Create oAuth App button.
Fill all the fields on the page.
Note
App Base Redirect URI and App Logo URL are used in the OAuth process when connecting.
Click the Create button and a block like the example below will be displayed:
Make sure the client_id and client_secret are stored securely. The Client secret is displayed once.

Connecting once (per customer)

OAuth often assumes that there are two applications, which integrate with each other. For this reason, it is not enough just to register an app, but a vPlan user will have to authorize the application in his vPlan environment.

As a developer, you facilitate for the vPlan user within your application a button to link with vPlan.
The vPlan user clicks the button, after which the user is referred to, for example:
https://developer.mostwanted.io/api/v1/oauth/authorize?client_id=90e1af5b-40ee-4d15-9b15-643b0360c581&redirect_uri=http:%2F%2Flocalhost:8080%2Foauth&response_type=code
De client_id en redirect_uri in bovenstaande voorbeeld URL vervang je met de gegevens die je hebt gehad bij het registreren in voorgaande hoofdstuk. De redirect_uri mag eventueel verlengt worden voor latere doeleinden.
Replace the client_id and redirect_uri in the above example URL with the data you had when registering in previous section. The redirect_uri may be extended for later purposes if necessary.
Tip
The structure of the url is described in Get authorization in the API documentation.
vPlan redirects the user to the login screen.
User now logs in with his vPlan credentials.
User answers the question if they want to authorize the integration for vPlan.
Example:
vPlan redirects the user to the redirect page specified during oAuth registration.
Since the authorization_code is valid for +/- 10 minutes, as a developer you exchange the code for a token.
Tip
See Token Exchange in the API documentation for more details.
As developer, you store the refresh_token encrypted at the client. This refresh_token is currently valid for one year.

Repeating connection

Now that the refresh_token is stored, it can be used to retrieve an access token and repeat the normal connection.
There are a number of times imaginable when a connection will be made:

An action is performed in the linked app that requires information from vPlan, or sends information to vPlan.
Through a scheduled interval, data is periodically sent to vPlan or retrieved from vPlan.

The refresh token eliminates the need for user interaction to establish the connection to vPlan.
When data from or to vPlan is needed, there are the following steps:

As a developer, swap the refresh_token for an access token.
Note
A refresh_token can only be used once.
vPlan sends an access token and a new refresh token.
You store the new refresh token encrypted at the client.
You connect to the vPlan API to perform the required actions.

API key

In vPlan, as a user with Administrator rights, you can easily create an API key. An API key gives you quick access to vPlan's API.
To create an API key, follow these steps in vPlan.

In the left menu bar in vPlan, go to Settings.
Then, click on Developers in the left menu bar.
To the right of the heading API keys, click on the plus icon.
Give your API key a name and click Save.
A pop-up screen will appear showing your API key in full once. Copy the API key using the appropriate button and save it securely.
To delete an API key, you can always return to the Developers menu at a later time. In that menu, click on the name of your API key and in the screen that follows click Delete.

Tip

In the Developer menu you can always see how many API requests you are using per day.

Replace your API key regularly

API keys are static keys that provide access to the data in vPlan. We therefore recommend that, as with passwords, you regularly replace an API key. In addition, it is wise to delete unused API keys.

Note

An API key is used by an integration developed by yourself, or by a partner of vPlan. Make sure that the administrator of the integration with the right knowledge and skills replaces the API key.

The steps to replace an API key are explained below.

Indicate to the administrator or partner that you want to change the API key
In vPlan go to Settings
Then click Developers </>
Add a new API key using the plus icon
Give the new keys to the administrator or partner
Wait for the approval of the administrator or partner
Then wait one or two more days
Check that the date and time of the 'last used' column for the old API key is no longer updated
Delete the old API key