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.com/v1

Additional resources:

Look at the playlist below for technical videos about our API.

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.
Default: 100
Maximum: 1.000

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.

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 the 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:2020-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

Slimmed down result

The query parameters show and hide allow clients to requests a limited set of properties.

In addition to reducing the amount of data transferred, this can be helpful in reducing errors caused by additional features added in a release update.

show specifies which properties the client will receive.
hide specifies which properties will be removed from the reponse.

Both must contain a comma separated list of properties.

For the properties of the main object this is pretty straigth forward. Subobjects added via eager loading come in 2 flavors:

  1. single subobject, e.g. collection or address for an order
    format: related object.property
  2. list of subobjects, e.g. order_rows
    format: related objects.*.property or related objects.item #.property

Please note that * can be used to show or hide all properties of a subobject.

Examples:

  • v1/order?show=code,type
  • v1/order?hide=created_at,updated_at
  • v1/order?with=collection,order_rows&show=code,type,collection.id,collection.source_type,order_rows.*.id
  • v1/order?with=collection,order_rows&hide=collection.id,collection.source_type,order_rows.*.id
  • v1/order?with=collection,order_rows&show=code,type,collection.id,collection.source_type,order_rows.0.id,order_rows.1.description
  • v1/order?with=collection&show=collection.*&hide=collection.id,collection.source_type
  • v1/order?with=order_rows&show=order_rows.*&hide=order_rows.*.id,order_rows.*.updated_at

As shown in the last example show and hide can be combined this is primarily usefull if you want specific properties from the main object and hide properties from related objects.

Eager loading

When retrieving a List or Single object, the with 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: ?with=attachments,cards.resources

If this example with 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 with options are stated with every object in this documentation.

Deprecated

The vPlan API is constantly improving, which means that today's endpoints and features 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.
Another option is retrieving the API messages.

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.

note

Objects that have the archive feature will per default not return archived objects.

Archived objects are not separate from unarchived objects, as such unique constraints still apply, i.e. an "active" or unarchived object cannot have the same value for a unique constraint as an archived object

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.

Rate Limits

The RateLimit headers are sent in responses to all the Api-Key or OAuth requests, they contain information about the amount of requests that can be made within the specified time window.

Header Description
RateLimit-Limit Maximum number of requests you're permitted to make per time window
RateLimit-Remaining Number of requests remaining in the current rate limit window.
RateLimit-Reset Time at which the current rate limit window resets in seconds.

Tips for optimizing an integration:

  • Use webhooks to be signaled when a certain event is triggered, instead of synchronizing every X minutes
  • Increase the interval between synchronizations, for example every 30 minutes instead of every 10 minutes
  • Create an Order with OrderRows in 1 request instead of separate requests per OrderRow
  • Use Eager loading, for example the Relation or Project info can be included when getting an Order in 1 request
  • Reduce retrieval of data. When an objects needs to be updated or referenced in another call having the information available without having to retrieve it every time can drastically reduce request counts Possible options are:
    • Store vPlan ids
    • Store entire vPlan objects
    • Cache vPlan ids
    • Cache entire vPlan objects

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
string <uuid>

Error reference, used for support requests

Array of objects (Error)
{
  • "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
403 FORBIDDEN Endpoint or action is not permitted
404 NOT FOUND Invalid endpoint, or an object id in request does not exist
405 METHOD NOT ALLOWED Requested method (GET, POST, PUT or DELETE) is not allowed for the endpoint

This error can also occur when parts of the endpoint are incorrect
e.g. updating an order without the required order_id PUT v1/order
422 UNPROCESSABLE ENTITY Validation on the request has failed
429 TOO MANY REQUESTS For more info look at Rate Limits
500 INTERNAL SERVER ERROR An internal error occurred

Look at Service Unavailable for responses given during maintenance.

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.

Empty values in created object

Scenario: you try to create an object and receive a 200 Ok response, but the object values are empty or using the default values.

Solution: your request is probably missing or having an invalid Content-Type header, make sure you provide it accordingly to your request e.g. application/json

Memory exhausted

A request can result in a 10005 Memory exhausted error.

It is likely that this request has worked in the past, but due to a growing amount of data now results in this error. Our API is unable to handle the large dataset resulting from your request.

The best way to prevent this error is ensure you use a combination of paging, filtering or reducing the amount of included data.

Report an issue

Most of our errors should be self explanatory, in the event of an Unknown error you can send a support request.

On creating an support request please provide the following information:

  • value of the errors[].reference from the error response
  • the endpoint of the request
  • the request body
  • the expected result
  • the actual result

Service Unavailable

While most of our maintenance is being performed without any downtime. An integration should take in account the following 2 responses:

Code Description Note
303 See Other vPlan Services are not available
503 Service Unavailable A release or maintenance is being performed

warning

The 303 See Other is a last resort redirect to give a proper unavailable notice page

The location that is given will end up in a HTTP 200 response with normal webpage content instead of json.

An integration should:

  • not follow the redirect
  • view the request as failed
  • and try again later.
Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)

Responses

Response samples

Content type
application/json
{
  • "reference": "97e3616c-e75c-46cc-a0fe-ac22f477864c",
  • "errors": [
    • {
      }
    ]
}

Retrieve Api Messages

The vPlan API is constantly improving, which means that today's endpoints and features could be replaced or removed in the future.

Where possible and appropriate, the API adds a deprecated header to the response. The API also offers this endpoint to retrieve any messages or warnings recorded during third party requests.

Integrators are expected to review these messages regularly and act accordingly.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
sort
string
Example: sort=updated_at:desc,id

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

limit
integer >= 1
Default: 100
Example: limit=50

maximum number of records given, see pagination for more info

offset
integer >= 0
Default: 0
Example: offset=0

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

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

used to filter the dataset, see filtering for more info

show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

X-REFERENCE
string <uuid>
Example: "05cad843-4214-4537-9010-90a7c3ba91f1"

Reference Tag, used for internal tracing and debugging of the request

Response Schema: application/json
id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

log_level
string
Enum: "info" "warning" "error"
method
string
Enum: "GET" "POST" "PUT" "DELETE"

used method that caused the message

endpoint
string

used endpoint that caused the message

query_params
string

used query parameters that caused the message

message_code
string

code to categorize the message

message
string

full message with details

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "id": "68e5bf7b-c525-4865-a50b-ad7654b8fd12",
  • "log_level": "warning",
  • "method": "GET",
  • "endpoint": "v1/order",
  • "query_params": {
    • "limit": 2000,
    • "with": "item,order_rows"
    },
  • "message_code": "RESULT_GT_100",
  • "message": "limit=2000, greater than max (1000), count 610",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Structure

Within vPlan we divide our objects in basically 3 sections:

  • configuration
  • third party data
  • base data

The configuration section are objects that are generaly setup at the start and should not change that often. Integrations will probably create a lot of these objects, or otherwise retrieve these objects to use the id's later on.

The third party data section are objects that are pure informational for the front end users. It exists primarily to facilitate integrations to update their data, and give the front end users the option to change values like the title, without losing the original information on screen. Most integrations use these objects to push there plannable objects to vPlan.

The base data section consists of object used in the normal day to day usage of vPlan: Most integrations use these objects to retreive information about the planning and send it back to the original system.

Synchronize data

The best way to synchronize changes in vPlan to another system is using webhooks.

An alternative would be using a GET list request and filter on the updated_at property.

Pro's and cons:

Subject Webhooks Filter on updated_at
Timeliness ✅ are sent out almost instantly ❌ has a delay since data is retrieved e.g. every hour or daily
Deletions ✅ have events to notify on deletions ❌ only shows the current objects
Related objects
e.g. a label added to a Card
✅ are available to reflect changes on related objects ❌ the updated_at on base objects is not changed if something is attached
Rate Limit 🟠 Rate Limit is calculated over incoming requests, Webhooks are outgoing requests and thus do not count towards this limit. 🟠 if there are no changes, the requests would be superfluous
multiple changes could be aggregated between runs
Dependencies ❌ need a webservice to listen to events sent from vPlan ✅ Retrieving data can be done by a simple client with internet

For on premise applications it can be difficult to expose a webservice to receive webhooks.

A possible solution could be to receive webhooks on services like Make.com or Zapier, store the events onto a OneDrive, Dropbox or Google Drive, and process these files on the on premise machine.

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.

warning

An API Key is static and gives unsupervised access to an account, to improve security we recommend to replace API Keys at least every 6 months.

Customers will receive reminders advising to replace their API Key.

As stated OAuth does not have this security risk.

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 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.com/
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
Flow type: authorizationCode
Token URL: https://developer.mostwanted.io/api/v1/oauth/token

Get authorization

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://example.com/callback

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

Response samples

Content type
application/json
{
  • "reference": "2fc891a6-d9b0-47a4-990f-3f24efe5b469",
  • "errors": [
    • {
      }
    ]
}

Token Exchange

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
required

User information to update

One of
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

Response Headers
X-NONCE
string <md5>
Example: "0cc830838614922c52cfff6e3931d4d8"

A nonce that can be used to prevent resubmission

ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
access_token
required
string <jwt>

Access token to authenticate with the external application

An access token is typically valid for a short period of time. The token is a JWT token, they payload contains the exp field specifying the date and time the token will expire.

refresh_token
required
string

Refresh token that can be used to obtain a new access_token.

Be sure to store this token securely, a refresh token ensures renewal of an expired access token. The refresh token is valid for 1 year, and only has a single use. Every request to the token endpoint ensures the creation of a new access token and a new refresh token.

token_type
required
string

Type of the returned token

expires_in
required
integer

Validity in seconds of the returned access token

Response samples

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

Me

The Me endpoint is a static endpoint that can be used to test if the authentication is valid. And also shows more details about what authentication is used.

Retrieve information about current authentication

Show information about user, authentication details and customer environment for the authentication that is used.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

X-REFERENCE
string <uuid>
Example: "05cad843-4214-4537-9010-90a7c3ba91f1"

Reference Tag, used for internal tracing and debugging of the request

Response Schema: application/json
type
string
Enum: "api-key" "user" "support_token" "thirdparty"
object (Environment)

Customer Environment details, please note that several system properties are not documented here.

object (User)
object (ApiKey)

Details for a Api Key connection

object (ThirdParty)

Details for a Third Party oAuth connection

Response samples

Content type
application/json
{
  • "type": "api-key",
  • "environment": {
    • "id": "3544e40a-1f46-49e5-806b-6bfd7ba29712",
    • "customer": "Foo Bar Inc",
    • "status": "sign_up",
    • "last_login": "2021-06-09T15:37:47Z",
    • "created_at": "2020-01-02T11:24:35Z",
    • "updated_at": "2020-01-02T11:24:35Z"
    },
  • "user": {
    • "id": "f69c8c01-4594-4c66-9440-f37c6b131b44",
    • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
    • "external_ref": "fb1033a2ed70",
    • "firstname": "string",
    • "lastname": "string",
    • "infix": "string",
    • "fullname": "string",
    • "gender": "M",
    • "email": "foo@example.com",
    • "mobile": "string",
    • "avatar": "string",
    • "about": "string",
    • "date_of_birth": "2019-08-24T14:15:22Z",
    • "role": "administrator",
    • "card_visibility": "all",
    • "language": "nl",
    • "timezone": "Europe/Amsterdam",
    • "notify_own_changes": true,
    • "created_at": "2020-01-02T11:24:35Z",
    • "updated_at": "2020-01-02T11:24:35Z",
    • "archived_at": "2021-07-06T11:24:35Z"
    },
  • "api-key": {
    • "id": "58a869d3-5740-479b-9a44-5400f80489fa",
    • "name": "Example Key for Foo Barring",
    • "last8": "qxhT5HzC",
    • "log_level": null,
    • "log_until": null,
    • "last_used": "2021-06-09T17:55:48Z",
    • "last_replace_reminder": null,
    • "disabled_until": null,
    • "created_at": "2020-01-02T11:24:35Z",
    • "updated_at": "2020-01-02T11:24:35Z"
    },
  • "thirdparty": {
    • "id": "561a0ec5-78ba-4837-9369-3c9fbb4f6975",
    • "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
    • "user_id": "f69c8c01-4594-4c66-9440-f37c6b131b44",
    • "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
    • "created_at": "2020-01-02T11:24:35Z",
    • "updated_at": "2020-01-02T11:24:35Z"
    }
}

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

Retrieve the Activity List

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
sort
string
Example: sort=updated_at:desc,id

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

limit
integer >= 1
Default: 100
Example: limit=50

maximum number of records given, see pagination for more info

offset
integer >= 0
Default: 0
Example: offset=0

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

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

used to filter the dataset, see filtering for more info

show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

archived
boolean
Default: false

per default archived objects are not returned, use this parameter to include archived objects.

combine with filter parameter to return only archived results ?archived&filter=archived_at:not:eq:null

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

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

X-REFERENCE
string <uuid>
Example: "05cad843-4214-4537-9010-90a7c3ba91f1"

Reference Tag, used for internal tracing and debugging of the request

Response Schema: application/json
count
integer

Total number of items that can be retrieved with respect of given filters

offset
integer

Offset of the result

limit
integer

Limit the number of results

Array of objects (Activity)

Response samples

Content type
application/json
{
  • "count": 1,
  • "offset": 0,
  • "limit": 100,
  • "data": [
    • {
      }
    ]
}

Create New Activity

Create a new Activity and store it

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: application/json
required

Activity to create

code
required
string
description
required
string
resource_type
string (ResourceType)
Enum: "employee" "machine" "cell"
default_duration
integer

default duration in minutes, used if an Activity is added to a Collection without time indicated

external_ref
string (ExternalRef)

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

archive
boolean

true will archive an object, false will unarchive an object, regardless of current state

Responses

Request samples

Content type
application/json
{
  • "resource_type": "employee",
  • "code": "PNT",
  • "description": "Paint it black",
  • "default_duration": 120,
  • "external_ref": "fb1033a2ed70",
  • "archive": false
}

Response samples

Content type
application/json
{
  • "id": "cc6fa5e0-0fd1-11e7-8911-02420a0a000f",
  • "resource_type": "employee",
  • "code": "PNT",
  • "description": "Paint it black",
  • "default_duration": 120,
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z",
  • "archived_at": "2021-07-06T11:24:35Z"
}

Retrieve Single Activity

Retrieve a single Activity

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
activity_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: cc6fa5e0-0fd1-11e7-8911-02420a0a000f

The Activity ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

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

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

resource_type
string (ResourceType)
Enum: "employee" "machine" "cell"
code
string
description
string
default_duration
integer

default duration in minutes, used if an Activity is added to a Collection without time indicated

external_ref
string (ExternalRef)

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

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

archived_at
string <date-time>

date / time that the object is archived

Response samples

Content type
application/json
{
  • "id": "cc6fa5e0-0fd1-11e7-8911-02420a0a000f",
  • "resource_type": "employee",
  • "code": "PNT",
  • "description": "Paint it black",
  • "default_duration": 120,
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z",
  • "archived_at": "2021-07-06T11:24:35Z"
}

Update Single Activity

Update a single Activity

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
activity_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: cc6fa5e0-0fd1-11e7-8911-02420a0a000f

The Activity ID

Request Body schema: application/json
required
code
required
string
description
required
string
resource_type
string (ResourceType)
Enum: "employee" "machine" "cell"
default_duration
integer

default duration in minutes, used if an Activity is added to a Collection without time indicated

external_ref
string (ExternalRef)

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

archive
boolean

true will archive an object, false will unarchive an object, regardless of current state

Responses

Request samples

Content type
application/json
{
  • "resource_type": "employee",
  • "code": "PNT",
  • "description": "Paint it black",
  • "default_duration": 120,
  • "external_ref": "fb1033a2ed70",
  • "archive": false
}

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Remove Single Activity

Remove a single Activity

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
activity_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: cc6fa5e0-0fd1-11e7-8911-02420a0a000f

The Activity ID

Responses

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Board

A Board is the place where activities are organized and where a team works together.

A Board with it's Stages represents the process steps a Collection will go through.

Within vPlan Collections are planned on a Board. That will result into one or more Cards with the details of the activities that need to be performed.

Retrieve Board List

Retrieve the Board List

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
sort
string
Example: sort=updated_at:desc,id

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

limit
integer >= 1
Default: 100
Example: limit=50

maximum number of records given, see pagination for more info

offset
integer >= 0
Default: 0
Example: offset=0

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

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

used to filter the dataset, see filtering for more info

show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

archived
boolean
Default: false

per default archived objects are not returned, use this parameter to include archived objects.

combine with filter parameter to return only archived results ?archived&filter=archived_at:not:eq:null

include
Array of strings
Items Enum: "automations" "entry_status"

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

Possible options are:

with
Array of strings
Items Enum: "checklists" "collections" "labels" "resources" "restricted_users" "stages" "statuses"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

X-REFERENCE
string <uuid>
Example: "05cad843-4214-4537-9010-90a7c3ba91f1"

Reference Tag, used for internal tracing and debugging of the request

Response Schema: application/json
count
integer

Total number of items that can be retrieved with respect of given filters

offset
integer

Offset of the result

limit
integer

Limit the number of results

Array of objects (Board)

Response samples

Content type
application/json
{
  • "count": 1,
  • "offset": 0,
  • "limit": 100,
  • "data": [
    • {
      }
    ]
}

Create New Board

Create a new Board and store it

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: application/json
required

Board to create

name
required
string
method
string
Default: "activity"
Enum: "activity" "percentage"

Defines how planning a collection interacts with the Stages of a Board.

  • activity - each stage has a specific set of possible activities defined
  • percentage - the total time of a collection is distributed according to the percentage set in each stage
object
Default: "[object Object]"

Days of the week that are considered workdays

Array of objects

Predefined custom fields useable for Collections in that Board

warning

Collection custom fields may deviate from board settings

color
string (ColorType)
Enum: "transparent" "red" "pink" "purple" "blue" "green" "yellow" "orange" "brown" "grey"
archive
boolean

true will archive an object, false will unarchive an object, regardless of current state

Array of objects (StatusCreate) >= 2 items
Default: "[object Object],[object Object],[object Object]"

Statusses available for the collections planned on this board

Array of objects (LabelCreate)

labels that can be used with the Board

Responses

Request samples

Content type
application/json
{
  • "name": "Production Process",
  • "method": "activity",
  • "workdays": {
    • "1": true,
    • "2": true,
    • "3": true,
    • "4": true,
    • "5": true,
    • "6": false,
    • "7": false
    },
  • "custom_fields": [
    • {
      }
    ],
  • "color": "transparent",
  • "archive": false,
  • "statuses": [
    • {
      },
    • {
      },
    • {
      }
    ],
  • "labels": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "4566d4f4-c0fa-4c72-a0ec-4e208affaaf5",
  • "name": "Production Process",
  • "method": "activity",
  • "workdays": {
    • "1": true,
    • "2": true,
    • "3": true,
    • "4": true,
    • "5": true,
    • "6": false,
    • "7": false
    },
  • "custom_fields": [
    • {
      }
    ],
  • "color": "transparent",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z",
  • "archived_at": "2021-07-06T11:24:35Z"
}

Retrieve Single Board

Retrieve a single Board

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
board_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4566d4f4-c0fa-4c72-a0ec-4e208affaaf5

The Board ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

include
Array of strings
Items Enum: "automations" "entry_status"

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

Possible options are:

with
Array of strings
Items Enum: "checklists" "collections" "labels" "resources" "restricted_users" "stages" "statuses"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

name
string
method
string
Default: "activity"
Enum: "activity" "percentage"

Defines how planning a collection interacts with the Stages of a Board.

  • activity - each stage has a specific set of possible activities defined
  • percentage - the total time of a collection is distributed according to the percentage set in each stage
object

Days of the week that are considered workdays

Array of objects

Predefined custom fields useable for Collections in that Board

warning

Collection custom fields may deviate from board settings

color
string (ColorType)
Enum: "transparent" "red" "pink" "purple" "blue" "green" "yellow" "orange" "brown" "grey"
created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

archived_at
string <date-time>

date / time that the object is archived

Response samples

Content type
application/json
{
  • "id": "4566d4f4-c0fa-4c72-a0ec-4e208affaaf5",
  • "name": "Production Process",
  • "method": "activity",
  • "workdays": {
    • "1": true,
    • "2": true,
    • "3": true,
    • "4": true,
    • "5": true,
    • "6": false,
    • "7": false
    },
  • "custom_fields": [
    • {
      }
    ],
  • "color": "transparent",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z",
  • "archived_at": "2021-07-06T11:24:35Z"
}

Update Single Board

Update a single Board

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
board_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4566d4f4-c0fa-4c72-a0ec-4e208affaaf5

The Board ID

Request Body schema: application/json
required
name
string
method
string
Default: "activity"
Enum: "activity" "percentage"

Defines how planning a collection interacts with the Stages of a Board.

  • activity - each stage has a specific set of possible activities defined
  • percentage - the total time of a collection is distributed according to the percentage set in each stage
object

Days of the week that are considered workdays

Array of objects

Predefined custom fields useable for Collections in that Board

warning

Collection custom fields may deviate from board settings

color
string (ColorType)
Enum: "transparent" "red" "pink" "purple" "blue" "green" "yellow" "orange" "brown" "grey"
archive
boolean

true will archive an object, false will unarchive an object, regardless of current state

Array of StatusCreate (object) or StatusUpdate (object) >= 2 items

Statusses available for the collections planned on this board

warning

Statusses that are not send will be removed from the board and cards if needed.

Array of objects

Change the order of the stages

Array of LabelCreate (object) or LabelUpdate (object)

labels that can be used with the Board

Array of objects (BoardResource)

the capacity for the resources per stage

Responses

Request samples

Content type
application/json
{
  • "name": "Production Process",
  • "method": "activity",
  • "workdays": {
    • "1": true,
    • "2": true,
    • "3": true,
    • "4": true,
    • "5": true,
    • "6": false,
    • "7": false
    },
  • "custom_fields": [
    • {
      }
    ],
  • "color": "transparent",
  • "archive": false,
  • "statuses": [
    • {
      },
    • {
      },
    • {
      }
    ],
  • "stages": [
    • {
      }
    ],
  • "labels": [
    • {
      }
    ],
  • "resources": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Remove Single Board

Remove a single Board

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
board_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4566d4f4-c0fa-4c72-a0ec-4e208affaaf5

The Board ID

Responses

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Label

There is no direct endpoint for interacting with a Label.

Labels can added or changed via the Board object.

id
string <uuid>

Unique identifier of Label

board_id
string <uuid>

Unique identifier of the Board

name
string
color
string (ColorType)
Enum: "transparent" "red" "pink" "purple" "blue" "green" "yellow" "orange" "brown" "grey"
created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

{
  • "id": "f60e9146-7755-42dc-a13b-6f9a79f12907",
  • "board_id": "4566d4f4-c0fa-4c72-a0ec-4e208affaaf5",
  • "name": "string",
  • "color": "transparent",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Status

There is no direct endpoint for interacting with a Status.

Statusses can added or changed via the Board object.

id
string <uuid>

Unique identifier of Status

board_id
string <uuid>

Unique identifier of the Board

name
string
color
string (ColorType)
Enum: "transparent" "red" "pink" "purple" "blue" "green" "yellow" "orange" "brown" "grey"
priority
integer

Priority used for sorting this object

entry
boolean

switch to show if this is the first status in a board

exit
boolean

switch to show if this is the last status in a board

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

{
  • "id": "be885fcf-8714-497e-9fbb-37a4b68f091d",
  • "board_id": "4566d4f4-c0fa-4c72-a0ec-4e208affaaf5",
  • "name": "Open",
  • "color": "transparent",
  • "priority": 0,
  • "entry": true,
  • "exit": false,
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

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

Retrieve the Collection List

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
sort
string
Example: sort=updated_at:desc,id

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

limit
integer >= 1
Default: 100
Example: limit=50

maximum number of records given, see pagination for more info

offset
integer >= 0
Default: 0
Example: offset=0

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

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

used to filter the dataset, see filtering for more info

show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

include
Array of strings
Items Value: "source"

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

Possible options are:

  • source - e.g. the Order

deprecated

This include is considered deprecated, and will be removed in the future. To obtain the same data as source use with with the following:

  • order.address
  • order.order_rows.item
  • order.relation
  • order.project
  • order.warehouse
  • order.order_rows.supplies_order_rows.order
  • order.order_rows.receives_order_rows.order
  • order.supplies_order_rows.order.relation
  • order.orderRows.receives_order
with
Array of strings
Items Enum: "activities" "attachments" "cards" "comments" "labels" "order" "followers" "checklists"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

X-REFERENCE
string <uuid>
Example: "05cad843-4214-4537-9010-90a7c3ba91f1"

Reference Tag, used for internal tracing and debugging of the request

Response Schema: application/json
count
integer

Total number of items that can be retrieved with respect of given filters

offset
integer

Offset of the result

limit
integer

Limit the number of results

Array of objects (Collection)

Response samples

Content type
application/json
{
  • "count": 1,
  • "offset": 0,
  • "limit": 100,
  • "data": [
    • {
      }
    ]
}

Create New Collection

Create a new Collection and store it

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: application/json
required

Collection to create

name
required
string
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.

Array of objects (Card)

array of Cards

warning

ignored if board_id is not present

Array of text (object) or numbers (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 (ExternalRef)

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

position
integer

Position in the backlog

status
string
Enum: "planned" "not_planned" "ignored"

status of the collection

  • planned - collection is planned, and has cards visible on a board
  • not_planned - collection is on backlog
  • ignored - collection is in the archive

warning

On update the status can only be changed from ignored to not_planned or from not_planned to ignored.

For other actions please look at:

Array of objects

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.

Array of objects

labels for this collection

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

Responses

Request samples

Content type
application/json
{
  • "board_id": "2661543f-47b3-4eaf-9728-723049764015",
  • "custom_fields": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {},
    • {
      }
    ],
  • "description": "3x Chair Lissabon",
  • "due_date": "2020-01-02",
  • "external_ref": "fb1033a2ed70",
  • "name": "Order 10199",
  • "position": 13,
  • "status": "not_planned",
  • "activities": [
    • {
      }
    ],
  • "labels": [
    • {
      }
    ]
}

Response samples

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

Retrieve Single Collection

Retrieve a single Collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

include
Array of strings
Items Value: "source"

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

Possible options are:

  • source - e.g. the Order

deprecated

This include is considered deprecated, and will be removed in the future. To obtain the same data as source use with with the following:

  • order.address
  • order.order_rows.item
  • order.relation
  • order.project
  • order.warehouse
  • order.order_rows.supplies_order_rows.order
  • order.order_rows.receives_order_rows.order
  • order.supplies_order_rows.order.relation
  • order.orderRows.receives_order
with
Array of strings
Items Enum: "activities" "attachments" "cards" "comments" "labels" "order" "followers" "checklists"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
id
required
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

board_id
string <uuid>

The Board the Collection is planned on

Array of text (object) or numbers (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>
end
string <date>

latest date from its Cards

external_ref
string (ExternalRef)

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

name
string
object

hashmap with additional information for the collection, received via Order

position
integer

Position in the backlog

source_type
string
Enum: "custom" "order" "clone"

states if the collection is created directly (custom), by cloning a collection or via an Order

start
string <date>

earliest date from its Cards

status
string
Enum: "planned" "not_planned" "ignored"

status of the collection

  • planned - collection is planned, and has cards visible on a board
  • not_planned - collection is on backlog
  • ignored - collection is in the archive

warning

On update the status can only be changed from ignored to not_planned or from not_planned to ignored.

For other actions please look at:

progress
string
Enum: "open" "partial" "done"

progress of the cards within the collection

  • open - all cards are on the first status
  • partial - not all cards are on the first or last status
  • done - all cards are on the last status
created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

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

Update Single Collection

Update a single Collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

Request Body schema: application/json
required
board_id
string <uuid>

The Board the Collection is planned on

Array of text (object) or numbers (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 (ExternalRef)

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

position
integer

Position in the backlog

status
string
Enum: "planned" "not_planned" "ignored"

status of the collection

  • planned - collection is planned, and has cards visible on a board
  • not_planned - collection is on backlog
  • ignored - collection is in the archive

warning

On update the status can only be changed from ignored to not_planned or from not_planned to ignored.

For other actions please look at:

Array of objects

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.

Array of objects

labels for this collection

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

Responses

Request samples

Content type
application/json
{
  • "board_id": "2661543f-47b3-4eaf-9728-723049764015",
  • "custom_fields": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {},
    • {
      }
    ],
  • "description": null,
  • "due_date": "2020-01-02",
  • "external_ref": "fb1033a2ed70",
  • "name": null,
  • "position": 13,
  • "status": "not_planned",
  • "activities": [
    • {
      }
    ],
  • "labels": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Remove Single Collection

Remove a single Collection

note

If the source_type of a Collection is order, this will change the status to ignored and remove the Collection from a board or backlog, but the Collection will still exist.

For complete removal remove the single order connected to the Collection.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

Responses

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Move Collection to Backlog

Move planned Collection to Backlog

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

Request Body schema: application/json
required
position
integer

Position in the backlog

related_collections
Array of strings <uuid>

Responses

Request samples

Content type
application/json
{
  • "position": 13,
  • "related_collections": [
    • "6c266875-53a4-4e13-8351-91eb87e0a0c6",
    • "a49d3a2f-e463-4f09-a178-2139a06d461f"
    ]
}

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Move Collection to Board

Move a not planned collection to Board and create Cards accordingly

note creating cards is an asynchronous process, new cards are almost but not instantly created

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

board_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 2661543f-47b3-4eaf-9728-723049764015

The board ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: application/json
required

Details used for planning the Collection

date
string <date>

Date for the first created card

force_stages
Array of strings <uuid>
position
integer

Position for the first created card

resources
Array of strings <uuid>

Resources added to the first created card

reverse
boolean
stage_id
string <uuid>

Stage for the first created card

status_id
string <uuid>

Status of the first card to be created

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "force_stages": [
    • "1ce1e25a-b64d-46d1-b38a-e05fd5717ac0",
    • "86bd3ad5-4d76-4aa3-a15a-b0bf0c62d87d",
    • "c8d4b144-a29f-480e-a28d-251f5cd8a477"
    ],
  • "position": 13,
  • "resources": [
    • "a225c108-a6ca-4343-8e10-fe10c841a688",
    • "d55ca612-5eab-4153-990a-7f7e059b184e",
    • "90a8e6da-6bc6-4ff8-95d7-ee73b0908928"
    ],
  • "reverse": true,
  • "stage_id": "1ce1e25a-b64d-46d1-b38a-e05fd5717ac0",
  • "status_id": "3c9fceef-c7ae-4bff-8450-f1a7b4dd47d8"
}

Response samples

Content type
application/json
{
  • "id": "4197da95-9298-41bc-9292-1215211619c2",
  • "board_id": "2661543f-47b3-4eaf-9728-723049764015",
  • "custom_fields": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {},
    • {
      }
    ],
  • "description": "3x Chair Lissabon",
  • "due_date": "2020-01-02",
  • "end": "2020-08-13",
  • "external_ref": "fb1033a2ed70",
  • "name": "Order 10199",
  • "meta": {
    • "bar": "foo",
    • "baz": "quux"
    },
  • "position": 13,
  • "source_type": "custom",
  • "start": "2020-01-02",
  • "status": "planned",
  • "progress": "open",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Attachment

An attachment can be one of the following:

  • a file uploaded to a Collection.
  • a link to an external system

The files uploaded are stored at our FS service. For the best experience, it is expected that links to an external system are accessable from any device or location.

In order to update an attachment it is currently required to first remove the old Attachment, and then add the new one.

Retrieve Attachment List

Retrieve the Attachment List for this collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

query Parameters
sort
string
Example: sort=updated_at:desc,id

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

limit
integer >= 1
Default: 100
Example: limit=50

maximum number of records given, see pagination for more info

offset
integer >= 0
Default: 0
Example: offset=0

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

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

used to filter the dataset, see filtering for more info

show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

with
Array of strings
Items Value: "collection"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

filename
string

Filename of the attachment

file
string <uri>

URI the file can be accessed on

warning if the type is fs.mostwanted.io the url will expire over time

type
string (AttachmentType)
Enum: "other" "fs.mostwanted.io"

Signifies wether the url given is from our FS service or has another source.

checksum
string <sha256>

Checksum of the file. This checksum is a SHA-256 hash of the contents of the file.

signature
string

Signature of the file, required for FS related url's, otherwise for informational purposes

bytes
integer >= 0

Size of the attachment in bytes

thumbnail
string <uri>

URL the thumbnail can be accessed on.

warning if the thumbnail_type is fs.mostwanted.io the the url will expire over time

thumbnail_type
string (AttachmentType)
Enum: "other" "fs.mostwanted.io"

Signifies wether the url given is from our FS service or has another source.

thumbnail_checksum
string <sha256>

Checksum of the thumbnail. This checksum is a SHA-256 hash of the contents of the thumbnail.

thumbnail_signature
string

Signature of the thumbnail, required for FS related url's, otherwise for informational purposes

thumbnail_bytes
integer >= 0

Size of the attachment in bytes

Upload New Attachment

Upload a file as a new Attachment and store it for this collection

The files are stored at our FS service.

note

With large files or files stored at a document management system like SharePoint, we highly recommend using Add New Attachment Link

warning

This endpoint does not support a base64 encoded upload.

For file upload we only support multipart/form-data.

Because oAuth is authenticated by a user, this is the user creating this attachment. For integrations that are not user specific, customers are advised to create a separate user specifically for this integration.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: multipart/form-data
required

Attachment to create

file
required
string <binary>

File to be added as attachment.

warning

Storage limitations of the customers subscription can result in an error HTTP 422 Unprocessable Entity.

warning

Files larger than approximately 30MB cannot be handled by the API. For large files please use a external system, and add the URL as attachment.

checksum
string

Checksum of the file. This checksum is a SHA-256 hash of the contents of the file.

If supplied the checksum must correspond with the uploaded file.

thumbnail
string <binary>

Thumbnail of the file.

If supplied it must be an image smaller than 1MB.

If not supplied and the uploaded file is smaller than 30MB, it will be generated in an asynchronous process.

thumbnail_checksum
string

Checksum of the thumbnail. This checksum is a SHA-256 hash of the contents of the file.

If supplied the checksum must correspond with the uploaded thumbnail.

Responses

Request samples

Content type
multipart/form-data
--__X_SAMPLE_BOUNDARY__
Content-Disposition: form-data; name="file"; filename="some_example.txt"
Content-Type: text/plain

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ornare lacinia lobortis. Praesent laoreet nunc a neque efficitur, dictum semper nibh congue. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aliquam condimentum consequat varius. Vivamus eget odio aliquam, pulvinar quam at, pellentesque risus. Proin ullamcorper, sapien a fringilla lacinia, ligula libero molestie mauris, vitae finibus enim libero non diam. Aliquam erat volutpat. Donec ex lorem, lobortis tempus venenatis sed, laoreet eu augue. Quisque accumsan mi quis ligula faucibus fringilla. Vivamus ut ex a dolor tincidunt tempor. Aenean eu consectetur nisi. Nunc iaculis at nibh quis mollis. Vestibulum placerat magna sed nisl malesuada euismod. In risus nisl, posuere ac mollis at, gravida quis diam. Integer id risus mattis, facilisis purus in, pharetra lectus. Sed tempus mi in gravida molestie.
--__X_SAMPLE_BOUNDARY__
Content-Disposition: form-data; name="checksum"

7709576d6e62147707ab36388c23ed96dc8721e503246c6d54fb3556185910c4
--__X_SAMPLE_BOUNDARY__
Content-Disposition: form-data; name="thumbnail"; filename="single_dot.jpg"
Content-Type: image/jpeg

ÿØÿàJFIFHHÿÛC

(1#%(:3=<9387@H\N@DWE78PmQW_bghg>Mqypdx\egcÿÛC//cB8BccccccccccccccccccccccccccccccccccccccccccccccccccÿÂÿÄÿÄÿÚ@ÿÄÿÚÿÄÿÚ?ÿÄÿÚ?ÿÄÿÚ?ÿÄÿÚ?!ÿÚÿÄÿÚ?ÿÄÿÚ?ÿÄÿÚ?ÿÙ
--__X_SAMPLE_BOUNDARY__
Content-Disposition: form-data; name="thumbnail_checksum"

639a79f429e70ef2761e19a5ba21c6059b8bd65b182a06d76df454ea6957025d
--__X_SAMPLE_BOUNDARY__--

Response samples

Add New Attachment Link

Add a link as new Attachment and store it for this collection

Possible usages are:

  • large files (e.g. cad files)
  • better version control, e.g. prevent having old versions in vPlan
  • enhanced security

note

It is expected that links to an external system are accessable from any device or location, especially the mobile apps.

Because oAuth is authenticated by a user, this is the user creating this attachment. For integrations that are not user specific, customers are advised to create a separate user specifically for this integration.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: application/json
required

Attachment to create

file
required
string <uri>

URI the file can be accessed on

warning if the type is fs.mostwanted.io the url will expire over time

filename
required
string

Filename of the attachment

checksum
string <sha256>

Checksum of the file. This checksum is a SHA-256 hash of the contents of the file.

signature
string

Signature of the file, required for FS related url's, otherwise for informational purposes

bytes
integer >= 0

Size of the attachment in bytes

thumbnail
string <uri>

URL the thumbnail can be accessed on.

warning if the thumbnail_type is fs.mostwanted.io the the url will expire over time

thumbnail_checksum
string <sha256>

Checksum of the thumbnail. This checksum is a SHA-256 hash of the contents of the thumbnail.

thumbnail_signature
string

Signature of the thumbnail, required for FS related url's, otherwise for informational purposes

thumbnail_bytes
integer >= 0

Size of the attachment in bytes

Responses

Request samples

Response samples

Retrieve Single Attachment

Retrieve a single Attachment from this collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

attachment_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 30317abe-987d-4f78-a427-93d129741c13

The Attachment ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

with
Array of strings
Items Value: "collection"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

filename
string

Filename of the attachment

file
string <uri>

URI the file can be accessed on

warning if the type is fs.mostwanted.io the url will expire over time

type
string (AttachmentType)
Enum: "other" "fs.mostwanted.io"

Signifies wether the url given is from our FS service or has another source.

checksum
string <sha256>

Checksum of the file. This checksum is a SHA-256 hash of the contents of the file.

signature
string

Signature of the file, required for FS related url's, otherwise for informational purposes

bytes
integer >= 0

Size of the attachment in bytes

thumbnail
string <uri>

URL the thumbnail can be accessed on.

warning if the thumbnail_type is fs.mostwanted.io the the url will expire over time

thumbnail_type
string (AttachmentType)
Enum: "other" "fs.mostwanted.io"

Signifies wether the url given is from our FS service or has another source.

thumbnail_checksum
string <sha256>

Checksum of the thumbnail. This checksum is a SHA-256 hash of the contents of the thumbnail.

thumbnail_signature
string

Signature of the thumbnail, required for FS related url's, otherwise for informational purposes

thumbnail_bytes
integer >= 0

Size of the attachment in bytes

Remove Single Attachment

Remove a single Attachment

note

a attachment can only be removed by the user that added it, or a user with the role administrator

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

attachment_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 30317abe-987d-4f78-a427-93d129741c13

The Attachment ID

Responses

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Card

A card is the basic object around which many operations in vPlan are centered. In vPlan the first view of a card shows basic information, when opening the card in vPlan more information and details are shown. A card always belongs to exactly one board.

Retrieve Card List

Retrieve the Card List for this collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

query Parameters
sort
string
Example: sort=updated_at:desc,id

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

limit
integer >= 1
Default: 100
Example: limit=50

maximum number of records given, see pagination for more info

offset
integer >= 0
Default: 0
Example: offset=0

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

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

used to filter the dataset, see filtering for more info

show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

include
Array of strings
Items Enum: "time_tracking_total" "resource_type_count" "resource_type_time"

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

Possible options are:

  • time_tracking_total
  • resource_type_count - count of linked resources by resource type
  • resource_type_time - sum of linked activities by resource type
with
Array of strings
Items Enum: "activities" "collection" "labels" "resources" "stage" "status" "time" "time_tracking"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
count
integer

Total number of items that can be retrieved with respect of given filters

offset
integer

Offset of the result

limit
integer

Limit the number of results

Array of objects (Card)

Response samples

Content type
application/json
{
  • "count": 1,
  • "offset": 0,
  • "limit": 100,
  • "data": [
    • {
      }
    ]
}

Create New Card

Create a new Card and store it for this collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: application/json
required

Card to create

stage_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
status_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
start
string <date>
end
string <date>
position
integer

Position of the card in a day

name
string

name specific for a Card

note

Collection has a name global for all cards, however a Card can have a specific name different from the rest.

Update the Collection name to update it for every Card.

description
string

description specific for a Card

note

Collection has a description global for all cards, however a Card can have a specific description different from the rest.

Update the Collection description to update it for every Card.

Array of objects

activities that need to be performed to complete this card

Array of objects
Array of objects

resources that are assigned to this Card

Responses

Request samples

Content type
application/json
{
  • "status_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "stage_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "start": "2020-01-02",
  • "end": "2020-01-05",
  • "position": 13,
  • "name": "Painting Order 10199",
  • "description": "Painting 3x Chair Lissabon Red",
  • "activities": [
    • {
      }
    ],
  • "labels": [
    • {
      }
    ],
  • "resources": [
    • {
      }
    ]
}

Response samples

Retrieve Single Card

Retrieve a single Card from this collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

card_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: fbd84744-4c8a-49fb-8764-92f5a85abe3a

The card ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

include
Array of strings
Items Enum: "time_tracking_total" "resource_type_count" "resource_type_time"

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

Possible options are:

  • time_tracking_total
  • resource_type_count - count of linked resources by resource type
  • resource_type_time - sum of linked activities by resource type
with
Array of strings
Items Enum: "activities" "collection" "labels" "resources" "stage" "status" "time" "time_tracking"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

collection_id
string <uuid>
status_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
stage_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
start
string <date>
end
string <date>
position
integer

Position of the card in a day

name
string

name specific for a Card

note

Collection has a name global for all cards, however a Card can have a specific name different from the rest.

Update the Collection name to update it for every Card.

description
string

description specific for a Card

note

Collection has a description global for all cards, however a Card can have a specific description different from the rest.

Update the Collection description to update it for every Card.

time
integer

Duration of the card in minutes

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "id": "92f8fd27-2ddb-4ca4-b42a-610b9d0349c9",
  • "collection_id": "4197da95-9298-41bc-9292-1215211619c2",
  • "status_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "stage_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "start": "2020-01-02",
  • "end": "2020-01-05",
  • "position": 13,
  • "name": "Painting Order 10199",
  • "description": "Painting 3x Chair Lissabon Red",
  • "time": 120,
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single Card

Update a single Card

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

card_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: fbd84744-4c8a-49fb-8764-92f5a85abe3a

The card ID

Request Body schema: application/json
required
status_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
stage_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
start
string <date>
end
string <date>
position
integer

Position of the card in a day

name
string

name specific for a Card

note

Collection has a name global for all cards, however a Card can have a specific name different from the rest.

Update the Collection name to update it for every Card.

description
string

description specific for a Card

note

Collection has a description global for all cards, however a Card can have a specific description different from the rest.

Update the Collection description to update it for every Card.

Array of objects

activities that need to be performed to complete this card

Array of objects
Array of objects

resources that are assigned to this Card

Responses

Request samples

Content type
application/json
{
  • "status_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "stage_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "start": "2020-01-02",
  • "end": "2020-01-05",
  • "position": 13,
  • "name": "Painting Order 10199",
  • "description": "Painting 3x Chair Lissabon Red",
  • "activities": [
    • {
      }
    ],
  • "labels": [
    • {
      }
    ],
  • "resources": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Remove Single Card

Remove a single Card

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

card_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: fbd84744-4c8a-49fb-8764-92f5a85abe3a

The card ID

Responses

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Split Card

Split time of Card into multiple cards

note splitting cards is an asynchronous process, new cards are almost but not instantly created

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

card_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: fbd84744-4c8a-49fb-8764-92f5a85abe3a

The card ID

Request Body schema: application/json
required
reverse
boolean

the order of splitting used for moving other cards of the collection

Array of objects

parts used for the creation of new cards

Responses

Request samples

Content type
application/json
{
  • "reverse": 13,
  • "date_parts": [
    • {
      },
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Comment

Retrieve Comment List

Retrieve the Comment List for this collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

query Parameters
sort
string
Example: sort=updated_at:desc,id

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

limit
integer >= 1
Default: 100
Example: limit=50

maximum number of records given, see pagination for more info

offset
integer >= 0
Default: 0
Example: offset=0

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

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

used to filter the dataset, see filtering for more info

show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

with
Array of strings
Items Value: "collection"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

text
string
Array of objects (CommentUserMention)

reserved for future usage

user
object

the user that created the comment

Response samples

Content type
application/json
{
  • "id": "a21c7cba-1990-4693-bff3-31b2b8fee795",
  • "text": "string",
  • "user_mentions": [
    • {
      }
    ],
  • "user": { }
}

Create New Comment

Create a new Comment and store it for this collection

Because oAuth is authenticated by a user, this is the user creating this comment. For integrations that are not user specific, customers are advised to create a separate user specifically for this integration.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: application/json
required

Comment to create

text
required
string
Array of objects (CommentUserMention)

reserved for future usage

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "user_mentions": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "a21c7cba-1990-4693-bff3-31b2b8fee795",
  • "text": "string",
  • "user_mentions": [
    • {
      }
    ],
  • "user": { }
}

Retrieve Single Comment

Retrieve a single Comment from this collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

comment_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a21c7cba-1990-4693-bff3-31b2b8fee795

The Comment ID

query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

with
Array of strings
Items Value: "collection"

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

Possible options are:

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

Response Schema: application/json
id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

Unique identifier

text
string
Array of objects (CommentUserMention)

reserved for future usage

user
object

the user that created the comment

Response samples

Content type
application/json
{
  • "id": "a21c7cba-1990-4693-bff3-31b2b8fee795",
  • "text": "string",
  • "user_mentions": [
    • {
      }
    ],
  • "user": { }
}

Update Single Comment

Update a single Comment

note

a comment can only be changed by the user that added it, or a user with the role administrator

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

comment_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a21c7cba-1990-4693-bff3-31b2b8fee795

The Comment ID

Request Body schema: application/json
required
text
string
Array of objects (CommentUserMention)

reserved for future usage

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "user_mentions": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Remove Single Comment

Remove a single Comment

note

a comment can only be removed by the user that added it, or a user with the role administrator

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
collection_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 4197da95-9298-41bc-9292-1215211619c2

The collection ID

comment_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a21c7cba-1990-4693-bff3-31b2b8fee795

The Comment ID

Responses

Response samples

Content type
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Item

An item is something that your company buys, sells, or produces. Items are used in order rows on an order.

Retrieve Item List

Retrieve the Item List

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
sort
string
Example: sort=updated_at:desc,id

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

limit
integer >= 1
Default: 100
Example: limit=50

maximum number of records given, see pagination for more info

offset
integer >= 0
Default: 0
Example: offset=0

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

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

used to filter the dataset, see filtering for more info

show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Responses

Response Headers
ETag
string <md5>
Example: "62a232916ac3a2f395791c108c295e8d"

Entity Tag, used for caching

X-REFERENCE
string <uuid>
Example: "05cad843-4214-4537-9010-90a7c3ba91f1"

Reference Tag, used for internal tracing and debugging of the request

Response Schema: application/json
count
integer

Total number of items that can be retrieved with respect of given filters

offset
integer

Offset of the result

limit
integer

Limit the number of results

Array of objects (Item)

Response samples

Content type
application/json
{
  • "count": 1,
  • "offset": 0,
  • "limit": 100,
  • "data": [
    • {
      }
    ]
}

Create New Item

Create a new Item and store it

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
query Parameters
show
string
Example: show=id,updated_at

limit the response to show only specific properties, see slimmed down result for more info

hide
string
Example: hide=created_at,updated_at

hide properties from the response, see slimmed down result for more info

Request Body schema: application/json
required

Item to create

code
required
string
description
required
string
stockmanagement
boolean
unit
string
type
string
location
string
note
string
external_ref
string (ExternalRef)

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

Responses

Request samples

Content type
application/json
{
  • "code": "B180",
  • "description": "Board 180",
  • "stockmanagement": true,
  • "unit": "Piece",
  • "type": "Item type",
  • "location": "3 Shelf",
  • "note": "A board that is 1800mm x 300mm x 20mm",
  • "external_ref": "fb1033a2ed70"
}

Response samples

Content type