vPlan API (v1)

vPlan is the easiest way to plan and track your work. Get insight and results. This API is available on: https://api.vplan.nl/v1

General

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:

  • for informational purposes only
    • this field is not used by vPlan but can be used freely to store extra information, e.g. for filtering
  • reserved for future use
    • this field is not used by vPlan at this moment but can be limited in possible values in the future
  • internally maintained
    • the value is calculated within vPlan and is read-only, the calculation could be async or triggered by an action

The examples below show default requirements and options. This information applies to all endpoints unless explicitly stated otherwise.

Pagination

The vPlan API supports pagination via the query parameters limit and offset.

Example: ?limit=50&offset=150

Limit is the maximum number of records given in a resulting dataset, use 0 for no limit.
Default: 0

Offset is the number of records to be skipped for the resulting dataset
Default: 0

If an offset is larger than the possible items that can be returned for the request, an empty data array will be returned.

The count property of a resultset can be used to determine how many calls must be made to retrieve all objects.

warning

currently default for limit is no limit, this will change in the future

Sorting

For sorting the resulting dataset use the query parameter sort with the format:

field:direction,field:direction

Example: ?sort=updated_at:desc,name

Colon : is the separator between the field and hte optional sorting order Default sorting order is ascending.

Comma , can be used to add multiple fields for sorting the dataset

warning

Will only work on main fields of the object and not on fields from included objects

Filtering

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:

field:operator:value

Example: ?filter=created_at:gt:2017-09-26,and,(id:not:starts_with:0000,or,id:contains:FFFF)

Colon : is the separator between the field, operator(s) and value.

Comma , can be used to combine filter statements by using ,and, or ,or,.

Braces (...) can be used to group filter statements.

The following operators are supported

operator description
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

warning

Currently the comma , and colon : are not supported within the filter value

Eager loading

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.

Example: ?include=attachments,cards.resources

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.

Deprecated

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.

External Reference

Almost every object relevant for integrations has a property named external_ref.

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.

Unique constraint

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.

warning

If in an order type or sub_type is given the value null the unique constraint will not be triggered. Use the value none instead.

Errors

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:

reference
required
string <uuid>

Error reference, used for support requests

errors
required
Array of objects (Error)
Copy
Expand all Collapse all
{
  • "reference": "6ad5af82-69bb-4e90-892e-45ec76d34954",
  • "errors":
    [
    ]
}

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.

Authentication

The vPlan API allows for three means of authentication, JWT Token, oAuth 2 or API Key.

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 {token}.

JwtToken

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
Bearer format "JWT"

Api-Key

The Api-Key is to be used in combination with X-Api-Env.

The two headers combined can be used as authentication.

Creating an Api-Key

Perform the following steps:

  • log into vPlan
  • in the menu click on Settings
  • in the menu click on API Keys
  • Click on the ADD KEY button
Security scheme type: API Key
Header parameter name: X-Api-Key

Api-Env

Api-Env is to be used in combination with Api-Key

Security scheme type: API Key
Header parameter name: X-Api-Env

Oauth2

Resources on oAuth:

Roles

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

Creating an app

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
Scopes:

    Get authorization

    get /oauth/authorize

    oAuth API

    https://{api_environment}.mostwanted.io/api/v1/oauth/authorize

    In order to create access tokens for a specific vPlan environment, the Resource Owner has to authorize the app to access their vPlan environment.

    To request authorization, the Resource Owner should be redirected to https://developer.mostwanted.io/api/v1/oauth/authorize

    The Resource Owner will be asked to log in to vPlan and allow this app to access the data in his vPlan environment.

    query Parameters
    client_id
    required
    string
    Example: client_id=176b8c0c-be44-4b0a-805f-28252932b48e

    Client ID of the app

    redirect_uri
    required
    string
    Example: redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

    A valid, TLS secured, redirect URI

    response_type
    required
    string
    Value: "code"

    Response type for the request

    state
    string
    Example: state=33cab0a8-ea0c-48e4-a090-71e9b95ab831

    Unique state, to prevent man-in-the-middle attacks

    Responses

    302

    Found

    400

    Bad Request

    401

    Unauthorized

    404

    Not Found

    409

    Conflict

    500

    Internal Server Error

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "errors":
      [
      ]
    }

    Token Exchange

    post /oauth/token

    oAuth API

    https://{api_environment}.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.

    warning The refresh token cannot be used more than once.

    Request Body schema: application/x-www-form-urlencoded

    User information to update

    One of
    • object
    • object
    client_id
    required
    string

    Client ID of the app

    client_secret
    required
    string

    Client Secret of the the ap

    redirect_uri
    required
    string

    A valid, TLS secured, redirect URI

    grant_type
    required
    string
    Enum: "authorization_code" "refresh_token"

    Grant Type for the token request

    code
    required
    string

    Authorization code for the token request

    state
    string

    Unique state, to prevent man-in-the-middle attacks

    Responses

    200

    Ok

    400

    Bad Request

    401

    Unauthorized

    409

    Conflict

    500

    Internal Server Error

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    • "refresh_token": "c3f42a9a1e78b8959882840aab940356",
    • "token_type": "access_token",
    • "expires_in": 3600
    }

    Activity

    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:

    • employees
    • machines
    • cells

    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 Activity List

    get /activity

    vPlan API

    https://{api_environment}.vplan.nl/v1/activity

    Retrieve the Activity List

    query Parameters
    sort
    string
    Example: sort=updated_at%3Adesc%2Cid

    field(s) for sorting the dataset, see sorting for more info

    limit
    integer >= 0
    Default: 0
    Example: limit=50

    maximum number of records given, see pagination for more info

    offset
    integer >= 0
    Default: 0

    the number of records to be skipped, see pagination for more info

    filter
    string
    Example: filter=created_at%3Agt%3A2017-09-26%2Cand%2C%28id%3Anot%3Astarts_with%3A0000%2Cor%2Cid%3Acontains%3AFFFF%29

    used to filter the dataset, see filtering for more info

    include
    Array of strings
    Items Enum: "resources" "time_tracking"

    object(s) included in the dataset, see eager loading for more info.

    Possible includes are:

    • resources - preferred resources
    • time_tracking

    Responses

    200

    Ok

    400

    Bad Request

    401

    Unauthorized

    404

    Not Found

    500

    Internal Server Error

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "count": 1,
    • "offset": 0,
    • "limit": 0,
    • "data":
      [
      ]
    }

    Create New Activity

    post /activity

    vPlan API

    https://{api_environment}.vplan.nl/v1/activity

    Create a new Activity and store it

    Request Body schema: application/json

    Activity to create

    code
    required
    string
    description
    required
    string
    resource_type
    string (ResourceType)
    Default: "employee"
    Enum: "employee" "machine" "cell"
    external_ref
    string (ExternalRef)

    Third-party reference of the object, for informational purposes only

    Responses

    201

    Created

    400

    Bad Request

    401

    Unauthorized

    403

    Forbidden

    404

    Not Found

    412

    Precondition Failed

    422

    Unprocessable Entity

    500

    Internal Server Error

    Request samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "cc6fa5e0-0fd1-11e7-8911-02420a0a000f",
    • "resource_type": "employee",
    • "code": "PNT",
    • "description": "Paint it black",
    • "external_ref": "fb1033a2ed70"
    }

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "cc6fa5e0-0fd1-11e7-8911-02420a0a000f",
    • "resource_type": "employee",
    • "code": "PNT",
    • "description": "Paint it black",
    • "external_ref": "fb1033a2ed70",
    • "created_at": "2018-01-02T11:24:35Z",
    • "updated_at": "2018-01-02T11:24:35Z"
    }