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.

Changelog

This is the change log for this documentation. For the changes in vPlan please visit the release notes

Please note that not every release will result in changes in the parts described in this documentation.

Date api version Description
7 aug 2019 2.31.0 added API-Key as authentication option
6 aug 2019 2.31.0 added info about sorting, pagination and filtering

Retrieve Example List

get /example
vPlan API
https://api.vplan.nl/v1/example

Retrieve Example List, with the possible query parameters for all Retrieve List Endpoints

warning this is not an existing endpoint

query Parameters
sort
string
Example: "updated_at:desc,created_at"

comma seperated list of fields, optionally combined with :desc or :asc for sorting order

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

limit
integer >= 0
Default: 0
Example: 50

the maximum number of records given in a resulting dataset, use 0 for no limit

warning current default is no limit, this will change in the future

offset
integer >= 0
Default: 0

the number of records to be skipped for the resulting dataset

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

Filter as stated: field:operator:value

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

include
string
Example: "warehouse,orderRows.item"

comma separated list of objects, the inclusion of sub-resources can be done using dot notation as shown in the example. Objects are included for every main resource in the response

Responses

200

Ok

400

Bad Request

401

Unauthorized

404

Not Found

500

Internal Server Error

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Retrieve Single Example

get /example/{example_id}
vPlan API
https://api.vplan.nl/v1/example/{example_id}

Retrieve Example Single, with the possible query parameter for all Retrieve Single Endpoints

warning this is not an existing endpoint

path Parameters
example_id
required
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
Example: "92f8fd27-2ddb-4ca4-b42a-610b9d0349c9"

The Example ID

query Parameters
include
string
Example: "warehouse,orderRows.item"

comma separated list of objects, the inclusion of sub-resources can be done using dot notation as shown in the example. Objects are included for every main resource in the response

Responses

200

Ok

401

Unauthorized

404

Not Found

500

Internal Server Error

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "92f8fd27-2ddb-4ca4-b42a-610b9d0349c9",
  • "foo": "bar",
  • "created_at": "2018-01-02T11:24:35Z",
  • "updated_at": "2018-01-02T11:24:35Z"
}

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://developer.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: "176b8c0c-be44-4b0a-805f-28252932b48e"

    Client ID of the app

    redirect_uri
    required
    string
    Example: "https://example.com/callback"

    A valid, TLS secured, redirect URI

    response_type
    required
    string
    Value:"code"

    Response type for the request

    state
    string
    Example: "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

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

    Token Exchange

    post /oauth/token
    oAuth API
    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.

    warning The refresh token cannot be used more than once.

    Request Body schema: application/x-www-form-urlencoded
    One of
    • Code
    • Refresh Token
    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

    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.vplan.nl/v1/activity

    Retrieve the Activity List

    Responses

    200

    Ok

    400

    Bad Request

    401

    Unauthorized

    404

    Not Found

    500

    Internal Server Error

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "data":
      [
      ]
    }

    Create New Activity

    post /activity
    vPlan API
    https://api.vplan.nl/v1/activity

    Create a new Activity and store it

    Request Body schema: application/json
    code
    required
    string
    description
    required
    string
    resource_type
    string
    Default: "employee"
    Enum:"employee" "machine" "cell"
    external_ref
    string

    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

    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

    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"
    }

    Retrieve Single Activity

    get /activity/{activity_id}
    vPlan API
    https://api.vplan.nl/v1/activity/{activity_id}

    Retrieve a single Activity

    path Parameters
    activity_id
    required
    string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
    Example: "cc6fa5e0-0fd1-11e7-8911-02420a0a000f"

    The Activity ID

    Responses

    200

    Ok

    401

    Unauthorized

    404

    Not Found

    500

    Internal Server Error

    Response samples

    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"
    }

    Update Single Activity

    put /activity/{activity_id}
    vPlan API
    https://api.vplan.nl/v1/activity/{activity_id}

    Update a single Activity

    path Parameters
    activity_id
    required
    string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
    Example: "cc6fa5e0-0fd1-11e7-8911-02420a0a000f"

    The Activity ID

    Request Body schema: application/json
    code
    required
    string
    description
    required
    string
    resource_type
    string
    Default: "employee"
    Enum:"employee" "machine" "cell"
    external_ref
    string

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

    Responses

    204

    No Content

    401

    Unauthorized

    403

    Forbidden

    404

    Not Found

    412

    Precondition Failed

    422

    Unprocessable Entity

    500

    Internal Server Error

    Request samples

    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

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

    Remove Single Activity

    delete /activity/{activity_id}
    vPlan API
    https://api.vplan.nl/v1/activity/{activity_id}

    Remove a single Activity

    path Parameters
    activity_id
    required
    string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
    Example: "cc6fa5e0-0fd1-11e7-8911-02420a0a000f"

    The Activity ID

    Responses

    204

    No Content

    401

    Unauthorized

    404

    Not Found

    500

    Internal Server Error

    Response samples

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

    Collection

    A collection represents a task, order, project, etc to be performed.

    It can be created on it self, or by creating an Order.

    A collection in the backlog or archive will have no Cards. A collection that is planned on a board must have cards.

    When planning a collection to a board, vPlan will create one or more cards, depending on the collection details and board settings.

    Retrieve Collection List

    get /collection
    vPlan API
    https://api.vplan.nl/v1/collection

    Retrieve the Collection List

    Responses

    200

    Ok

    401

    Unauthorized

    404

    Not Found

    500

    Internal Server Error

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "data":
      [
      ]
    }

    Create New Collection

    post /collection
    vPlan API
    https://api.vplan.nl/v1/collection

    Create a new Collection and store it

    Request Body schema: application/json
    name
    required
    string
    custom_fields
    Array of text (object) or number (object) or date (object) or checkbox (object) or email (object) or link (object) or phone (object)

    Custom field objects

    description
    string
    due_date
    string <date>
    external_ref
    string

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

    board_id
    string <uuid>

    Can be use to directly plan a collection an a Board, an array of cards is required next to this.

    With null or not present the Collection will be put on the backlog.

    cards
    Array of object

    array of Cards

    warning

    ignored if board_id is not present

    position
    integer

    Position in the backlog

    activities
    Array of object

    activities that need to be performed for this collection

    note

    When a Collection is planned these activities will be used to create the Cards and divided to them accordingly.

    When a Collection is put back to the backlog the activities of the Cards are used to recreate the activities for the collection.

    labels
    Array of object

    labels for this collection

    When a Collection is planned these labels are added on every Card created.

    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

    application/json
    Copy
    Expand all Collapse all
    {
    • "board_id": "2661543f-47b3-4eaf-9728-723049764015",
    • "cards":
      [
      ],
    • "id": "4197da95-9298-41bc-9292-1215211619c2",
    • "custom_fields":
      [
      ],
    • "description": "3x Chair Lissabon",
    • "due_date": "2018-01-02",
    • "external_ref": "fb1033a2ed70",
    • "name": "Order 10199",
    • "position": 13,
    • "activities":
      [
      ],
    • "labels":
      [
      ]
    }

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "4197da95-9298-41bc-9292-1215211619c2",
    • "board_id": "2661543f-47b3-4eaf-9728-723049764015",
    • "custom_fields":
      [
      ],
    • "description": "3x Chair Lissabon",
    • "due_date": "2018-01-02",
    • "end": "2018-08-13",
    • "external_ref": "fb1033a2ed70",
    • "name": "Order 10199",
    • "meta":
      {
      },
    • "position": 13,
    • "source_type": "custom",
    • "start": "2018-01-02",
    • "status": "not_planned",
    • "created_at": "2018-01-02T11:24:35Z",
    • "updated_at": "2018-01-02T11:24:35Z"
    }

    Retrieve Single Collection

    get /collection/{collection_id}
    vPlan API
    https://api.vplan.nl/v1/collection/{collection_id}

    Retrieve a single Collection

    path Parameters
    collection_id
    required
    object

    The collection ID

    Responses

    200

    Ok

    401

    Unauthorized

    404

    Not Found

    500

    Internal Server Error

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "4197da95-9298-41bc-9292-1215211619c2",
    • "board_id": "2661543f-47b3-4eaf-9728-723049764015",
    • "custom_fields":
      [
      ],
    • "description": "3x Chair Lissabon",
    • "due_date": "2018-01-02",
    • "end": "2018-08-13",
    • "external_ref": "fb1033a2ed70",
    • "name": "Order 10199",
    • "meta":
      {
      },
    • "position": 13,
    • "source_type": "custom",
    • "start": "2018-01-02",
    • "status": "not_planned",
    • "created_at": "2018-01-02T11:24:35Z",
    • "updated_at": "2018-01-02T11:24:35Z"
    }

    Update Single Collection

    put /collection/{collection_id}
    vPlan API
    https://api.vplan.nl/v1/collection/{collection_id}

    Update a single Collection

    path Parameters
    collection_id
    required
    object

    The collection ID

    Request Body schema: application/json
    labels
    Array of object

    labels for this collection

    When a Collection is planned these labels are added on every Card created.

    custom_fields
    Array of text (object) or number (object) or date (object) or checkbox (object) or email (object) or link (object) or phone (object)

    Custom field objects

    description
    string

    warning

    if changed this will update the description of every Card within the collection despite a possible different description on a Card

    due_date
    string <date>
    external_ref
    string

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

    name
    string

    warning

    if changed this will update the name of every Card within the collection despite a possible different name on a Card

    board_id
    string <uuid>

    The Board the Collection is planned on

    position
    integer

    Position in the backlog

    activities
    Array of object

    activities that need to be performed for this collection

    note

    When a Collection is planned these activities will be used to create the Cards and divided to them accordingly.

    When a Collection is put back to the backlog the activities of the Cards are used to recreate the activities for the collection.

    Responses

    204

    No Content

    401

    Unauthorized

    403

    Forbidden

    404

    Not Found

    412

    Precondition Failed

    422

    Unprocessable Entity

    500

    Internal Server Error

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "4197da95-9298-41bc-9292-1215211619c2",
    • "board_id": "2661543f-47b3-4eaf-9728-723049764015",
    • "custom_fields":
      [
      ],
    • "description": null,
    • "due_date": "2018-01-02",
    • "external_ref": "fb1033a2ed70",
    • "name": null,
    • "position": 13,
    • "activities":
      [
      ],
    • "labels":