This API reference contains the documentation for all supported third-party vPlan objects. There are also undocumented endpoints, that are accessible with the API token, these endpoints are used by the application itself. Undocumented endpoints are unsupported for third-party use. These endpoints are subject to change without prior warning.
For every object a data structure table is given, the field description can end with:
The examples below show default requirements and options. This information applies to all endpoints unless explicitly stated otherwise.
The vPlan API supports pagination via the query parameters
Limit is the maximum number of records given in a resulting dataset, use
0 for no limit.
Offset is the number of records to be skipped for the resulting dataset
If an offset is larger than the possible items that can be returned for the request, an empty data array will be returned.
count property of a resultset can be used to determine how many calls must be made to retrieve all objects.
currently default for limit is no limit, this will change in the future
For sorting the resulting dataset use the query parameter
sort with the format:
: is the separator between the field and hte optional sorting order
Default sorting order is ascending.
, can be used to add multiple fields for sorting the dataset
Will only work on main fields of the object and not on fields from included objects
On the list endpoints it is possible to filter the result set given.
To apply a filter use the
filter query parameter with the format:
: is the separator between the field, operator(s) and value.
, can be used to combine filter statements by using
) can be used to group filter statements.
The following operators are supported
|eq||equal to the given value|
|gt||greater than the given value|
|gte||greater than or equal to the given value|
|lt||lesser than the given value|
|lte||lesser than or equal to the given value|
|not||negation of the operator that follows it|
|contains||has occurrence of the given value|
|starts_with||starts with the given value|
|end_with||ends with the given value|
Currently the comma , and colon : are not supported within the filter value
When retrieving a List or Single object, the
include query parameter allows to eager load
and retrieve related objects with one call.
It consists of a comma separated list of objects, using the dot . as separator for subobjects.
If this example include was performed on the Collection List, It would retrieve every collection, and with every collection its attachments, it would also retrieve all the cards of every collection, and finally it would return every resource from every card of every collection.
The first layer of possible include options are stated with every object in this documentation.
The vPlan API is constantly improving, which means that today's endpoints and feature could be replaced or removed in the future.
Within this documentation endpoints, parameters or fields can be flagged as Deprecated.
Newly created integrations should not use anything marked as deprecated.
Existing integrations that use anything marked as deprecated, should alter that part of the integration in the near future, in order to prevent possible future errors.
For deprecated endpoints the API will send a
Deprecated header with a description.
Example: GET v1/collection/detail is deprecated and will be removed in future versions
Integrations are expected to look out for this header, and act accordingly.
Almost every object relevant for integrations has a property named
In principal this is not a field vPlan uses it self. However if it has a value the vPlan frontend will block certain manually changes for a user.
The main goal for this property is to provide integrations with a location to store the unique identifier of the source object.
The external_ref has the requirement that it must be unique, within that object. If you try to create an object with an already existing external_ref the vPlan API give an error "HTTP 422 Unprocessable entity", with a description stating "Duplicate entry".
For Orders the unique key is external_ref combined with type and sub_type.
If in an order type or sub_type is given the value
nullthe unique constraint will not be triggered. Use the value
In the event the request results in an error of any kind, the API will respond with an json error. If you receive any other kind of error there must be a connection issue somewhere down the line.
An error will always be in the following format:
Error reference, used for support requests
Array of objects (Error)
The API will use different HTTP status codes if suitable. The status codes commonly seen within this API, are in the table down below. Please note that this is not a complete list.
|HTTP Code||Description||Example occurrences|
|400||BAD REQUEST||Invalid request given, e.g. limit=-15 as query parameter given|
|401||UNAUTHORIZED||Accesstoken is expired|
|404||NOT FOUND||Invalid endpoint, or an object id in request does not exist|
|405||METHOD NOT ALLOWED||Requested method (GET, POST, PUT, DELETE) is not allowed for the the endpoint|
|422||UNPROCESSABLE ENTITY||Validation on the request has failed|
|500||INTERNAL SERVER ERROR||An internal error occurred|
The HTTP Status code gives an indication of the kind of error. More detailed information is available in the error message. The error message should be enough to correct the request accordingly.
An error message stating Unknown, indicates an error that is currently not forseen within our API. In that case you can send a support request.
By suppling the reference of an error we will be able to handle any support requests quicker.
API Keys are great for rapid prototyping and easy access. For increased security, integrations should strive to use OAuth 2, especially if designed for multiple customers.
In this document the headers are included in the examples, the credentials that need to be filled in this header are replaced with a placeholder
A JWT 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 construct a token on its own.
The header contains information about the token (type, signature algorithm). The payload contains information about the user and the validity of the token (username, expiration date, issuer). The signature is a hash created with the defined algorithm in the header, signing the information in the token.
|Security scheme type:||HTTP|
|HTTP Authorization Scheme||bearer|
The Api-Key is to be used in combination with X-Api-Env.
The two headers combined can be used as authentication.
Perform the following steps:
|Security scheme type:||API Key|
|Header parameter name:||X-Api-Key|
Api-Env is to be used in combination with Api-Key
|Security scheme type:||API Key|
|Header parameter name:||X-Api-Env|
Resources on oAuth:
|OAuth 2 Role||Application|
|Client||Application using this API|
|Resource Server||The vPlan API service|
|Authorization Server||Most Wanted OAuth 2 Authorization Server|
|Resource Owner||The user of the vPlan environment|
To create an app, that users can connect to their vPlan environment, go to https://developer.vplan.nl/
Registration of the app provides a
client id and
client secret. This information is specific to the app.
The client secret should never be shared publicly.
Registration requires a redirect URI, this should be the base URI to which all callbacks will be performed, this URI should be publicly accessible.
|Security scheme type:||OAuth2|
|authorizationCode OAuth Flow|
Authorization URL: https://developer.mostwanted.io/api/v1/oauth/authorize
Token URL: https://developer.mostwanted.io/api/v1/oauth/token
After obtaining an authorization code, an access token can be requested on https://developer.mostwanted.io/api/v1/oauth/token
This request will result in an access token and a refresh token.
The refresh token can also be used on this endpoint to create a new access token and refresh token.
warningThe refresh token cannot be used more than once.
User information to update
Client ID of the app
Client Secret of the the ap
A valid, TLS secured, redirect URI
Enum: "authorization_code" "refresh_token"
Grant Type for the token request
Authorization code for the token request
Unique state, to prevent man-in-the-middle attacks
Internal Server Error
An activity is a service that your company performs or an operation that is needed to produce an item.
vPlan has three types of activities:
An activity can only be performed by resources of the same type.
Activities are used in:
To be able to plan an order you will need to set up a board within vPlan, with stages connected to specific activities. See Create planboard in our support documentation.
Retrieve the Activity List
field(s) for sorting the dataset, see sorting for more info
integer >= 0
maximum number of records given, see pagination for more info
integer >= 0
the number of records to be skipped, see pagination for more info
used to filter the dataset, see filtering for more info
Internal Server Error
Create a new Activity and store it
Activity to create
Enum: "employee" "machine" "cell"
Third-party reference of the object, for informational purposes only
Internal Server Error