logo
API docs by Redocly

vPlan API (v1)

vPlan Support: support@vplan.com URL: https://support.vplan.com Terms of Service

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
Authorization URL: https://developer.mostwanted.io/api/v1/oauth/authorize
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

Response samples

Content type
application/json
{}

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

Content type
application/json
{}

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

Content type
application/json
{}

Response samples

Content type
application/json
{}

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

Response samples

Content type
application/json
{}

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

Content type
application/json
{}

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
application/json
{
  • "id": "25e01e69-57d2-4331-b1ca-5e13c0c99612",
  • "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",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Single Item

Retrieve a single Item

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
item_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 25e01e69-57d2-4331-b1ca-5e13c0c99612

The Item 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

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

code
string
description
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

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "id": "25e01e69-57d2-4331-b1ca-5e13c0c99612",
  • "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",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single Item

Update a single Item

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
item_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 25e01e69-57d2-4331-b1ca-5e13c0c99612

The Item ID

Request Body schema: application/json
required

Item to update

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
application/json
{
  • "reference": "689fba08-56b0-468c-ad97-809e7dab8a45",
  • "errors": [
    • {
      }
    ]
}

Remove Single Item

Remove a single Item

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
item_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 25e01e69-57d2-4331-b1ca-5e13c0c99612

The Item ID

Responses

Response samples

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

Order

vPlan has five types of orders; Sales, Quotation, Purchase, Production and Project:

  • Sales Order represents a sale, i.e. a product or service delivered to a relation.
  • Quotation Order represents a quotation, i.e. an offer for goods or services to a relation.
  • Purchase Order represents a purchase, i.e. a product or service acquired from a relation.
  • Production Order represents a production, i.e. a product is produced.
  • Project Order represents a project, i.e. umbrella of activities performed for a relation.

note A customer cannot maintain an Orders within vPlan, it should be maintained by the integrations that created it, and is only visible as integration data via a Collection.

Order affiliation to Collection

An order is a helper object for creating a collection.

Its purpose is to give an integration the option to maintain data consistency, while giving the customer a way to manually add or change the details of a collection.

On creation of an order, a collection is automatically created. That collection could, depending on the settings, be automatically planned via an asynchronous process. This process uses the promised date of order.

On update of an order, a collection is automatically synchronized via an asynchronous process.

The collection will be constructed using the following data if available:

Collection Order On Create On update
name code initial value updated if not manually changed
description quantity and description initial value updated if not manually changed
due_date promised_date or else desired_date initial value updated if not manually changed ¹
meta
- order_type type initial value updated
- order_status status initial value updated
- address order.address initial value updated
- relation relation.name initial value updated
- project project.name initial value updated
- promised_date promised_date initial value updated ¹
- desired_date desired_date initial value updated ¹
activities rows
- id activity.id initial value only updated for the backlog
- time unit * quantity ² initial value only updated for the backlog

¹: Dates changed in the Order will not affect the actual planning, it could give a warning icon within the current plan boards.

²: Time is calculated to minutes based on the unit and quantity, and rounded to a whole number:

unit time
minutes quantity
hours 60 * quantity
days 3600 * quantity
[other] 0

Retrieve Order List

Retrieve the Order 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 Enum: "orderRows" "suppliesOrderRows"

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

Possible options are:

deprecated

These includes are considered deprecated, and will be removed in the future. Use the equivalent with snake_case option (e.g. order_rows).

with
Array of strings
Items Enum: "address" "item" "order_rows" "collection" "project" "relation" "warehouse" "supplies_order_rows"

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 (Order)

Response samples

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

Create New Order

Create a new Order and store it

note

It is possible to create an Order with Rows in one request.
It is not possible to update both in one request.

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

Order to create

type
required
string (Type)
Enum: "Production" "Project" "Purchase" "Quotation" "Sales"
code
required
string
description
required
string
quantity
number <double>
external_url
string
sub_type
string

for informational purposes only

status
string
Enum: "open," "partial" "completed" "cancelled"
note
string

note, use <br> for new lines

contact
string
relation_ref
string

the reference from the relation of the order

date
string <date>

date when the order was placed

desired_date
string <date>
promised_date
string <date>

promised delivery date, required in case of automatic planning

delivered_date
string <date>
collection_id
string <uuid>

id for the related collection Collection

item_id
string <uuid>

id for the Item produced by this Order

project_id
string <uuid>

id for the Project this Order belongs to

relation_id
string <uuid>

id for the Relation of the Order

warehouse_id
string <uuid>

id for the Warehouse of the Order

external_ref
string (ExternalRef)

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

object

the Project this Order belongs to, alternative to project_id property

object

the Warehouse of the Order, alternative to warehouse_id property

object

the Item produced by this Order, alternative to item_id property

object

the Relation of the Order, alternative to relation_id property

object or null

the delivery address for the order

Array of uuid (string) or Row Object with id (object)

optional Order Rows this Order supplies to, read Supplies and Receives for more information

board_id
string <uuid>

Initial board_id used in the collection that is created with the Order

note

this can only be set while creating an Order and can only be updated via the Collection

Array of objects (Order Row)

Responses

Request samples

Content type
application/json
{
  • "type": "Sales",
  • "code": "S00235",
  • "description": "Furniture plot no 180",
  • "quantity": 42,
  • "external_url": "https://www.example.nl/url",
  • "sub_type": "precalculation",
  • "status": "foo",
  • "note": "Paint colors:\nInner: 4344-R58B\nOuter: S 0585-Y80R\n",
  • "contact": "John Doe",
  • "relation_ref": "CU1701246",
  • "date": "2020-05-02",
  • "desired_date": "2020-05-15",
  • "promised_date": "2020-05-22",
  • "delivered_date": "2020-05-14",
  • "collection_id": "60df67b0-aff3-4212-904c-46a42ea6d6f6",
  • "item_id": "25e01e69-57d2-4331-b1ca-5e13c0c99612",
  • "project_id": "5a6b204f-4b03-4f00-b0d8-3a6449b07040",
  • "relation_id": "401f7e85-af41-4d03-9c07-13cb7d1a4ea7",
  • "warehouse_id": "b006d5fd-b5f1-45c5-94bd-f60a50b79771",
  • "external_ref": "fb1033a2ed70",
  • "project": {
    • "id": "5a6b204f-4b03-4f00-b0d8-3a6449b07040"
    },
  • "warehouse": {
    • "id": "b006d5fd-b5f1-45c5-94bd-f60a50b79771"
    },
  • "item": {
    • "id": "25e01e69-57d2-4331-b1ca-5e13c0c99612"
    },
  • "relation": {
    • "id": "401f7e85-af41-4d03-9c07-13cb7d1a4ea7"
    },
  • "address": {
    • "street1": "Putman Cramerstraat 51a",
    • "street2": "first floor",
    • "postcode": "7468 BH",
    • "city": "Enter",
    • "state": "Overijssel",
    • "country": "Netherlands",
    • "latitude": 52.3156048,
    • "longitude": 6.496432
    },
  • "suppliesOrderRows": [
    • "194ab6b2-08f5-4403-9fb9-916f33c145bc"
    ],
  • "board_id": "4566d4f4-c0fa-4c72-a0ec-4e208affaaf5",
  • "orderRows": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": "28c8f918-f461-4a9c-9108-6bde41b4623e",
  • "type": "Sales",
  • "code": "S00235",
  • "description": "Furniture plot no 180",
  • "quantity": 42,
  • "external_url": "https://www.example.nl/url",
  • "sub_type": "precalculation",
  • "status": "foo",
  • "note": "Paint colors:\nInner: 4344-R58B\nOuter: S 0585-Y80R\n",
  • "contact": "John Doe",
  • "relation_ref": "CU1701246",
  • "date": "2020-05-02",
  • "desired_date": "2020-05-15",
  • "promised_date": "2020-05-22",
  • "delivered_date": "2020-05-14",
  • "meta": {
    • "bar": "foo",
    • "baz": "quux"
    },
  • "collection_id": "60df67b0-aff3-4212-904c-46a42ea6d6f6",
  • "item_id": "25e01e69-57d2-4331-b1ca-5e13c0c99612",
  • "project_id": "5a6b204f-4b03-4f00-b0d8-3a6449b07040",
  • "relation_id": "401f7e85-af41-4d03-9c07-13cb7d1a4ea7",
  • "warehouse_id": "b006d5fd-b5f1-45c5-94bd-f60a50b79771",
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Single Order

Retrieve a single Order

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
order_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 28c8f918-f461-4a9c-9108-6bde41b4623e

The Order 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: "orderRows" "suppliesOrderRows"

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

Possible options are:

deprecated

These includes are considered deprecated, and will be removed in the future. Use the equivalent with snake_case option (e.g. order_rows).

with
Array of strings
Items Enum: "address" "item" "order_rows" "collection" "project" "relation" "warehouse" "supplies_order_rows"

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

type
string (Type)
Enum: "Production" "Project" "Purchase" "Quotation" "Sales"
code
string
description
string
quantity
number <double>
external_url
string
sub_type
string

for informational purposes only

status
string
Enum: "open," "partial" "completed" "cancelled"
note
string

note, use <br> for new lines

contact
string
relation_ref
string

the reference from the relation of the order

date
string <date>

date when the order was placed

desired_date
string <date>
promised_date
string <date>

promised delivery date, required in case of automatic planning

delivered_date
string <date>
object

hashmap with additional information for the Order, for informational purposes only

collection_id
string <uuid>

id for the related collection Collection

item_id
string <uuid>

id for the Item produced by this Order

project_id
string <uuid>

id for the Project this Order belongs to

relation_id
string <uuid>

id for the Relation of the Order

warehouse_id
string <uuid>

id for the Warehouse of the Order

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

Response samples

Content type
application/json
{
  • "id": "28c8f918-f461-4a9c-9108-6bde41b4623e",
  • "type": "Sales",
  • "code": "S00235",
  • "description": "Furniture plot no 180",
  • "quantity": 42,
  • "external_url": "https://www.example.nl/url",
  • "sub_type": "precalculation",
  • "status": "foo",
  • "note": "Paint colors:\nInner: 4344-R58B\nOuter: S 0585-Y80R\n",
  • "contact": "John Doe",
  • "relation_ref": "CU1701246",
  • "date": "2020-05-02",
  • "desired_date": "2020-05-15",
  • "promised_date": "2020-05-22",
  • "delivered_date": "2020-05-14",
  • "meta": {
    • "bar": "foo",
    • "baz": "quux"
    },
  • "collection_id": "60df67b0-aff3-4212-904c-46a42ea6d6f6",
  • "item_id": "25e01e69-57d2-4331-b1ca-5e13c0c99612",
  • "project_id": "5a6b204f-4b03-4f00-b0d8-3a6449b07040",
  • "relation_id": "401f7e85-af41-4d03-9c07-13cb7d1a4ea7",
  • "warehouse_id": "b006d5fd-b5f1-45c5-94bd-f60a50b79771",
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single Order

Update a single Order

note

Look at Update Single OrderRow to update Order Rows.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
order_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 28c8f918-f461-4a9c-9108-6bde41b4623e

The Order ID

Request Body schema: application/json
required
type
string (Type)
Enum: "Production" "Project" "Purchase" "Quotation" "Sales"
code
string
description
string
quantity
number <double>
external_url
string
sub_type
string

for informational purposes only

status
string
Enum: "open," "partial" "completed" "cancelled"
note
string

note, use <br> for new lines

contact
string
relation_ref
string

the reference from the relation of the order

date
string <date>

date when the order was placed

desired_date
string <date>
promised_date
string <date>

promised delivery date, required in case of automatic planning

delivered_date
string <date>
collection_id
string <uuid>

id for the related collection Collection

item_id
string <uuid>

id for the Item produced by this Order

project_id
string <uuid>

id for the Project this Order belongs to

relation_id
string <uuid>

id for the Relation of the Order

warehouse_id
string <uuid>

id for the Warehouse of the Order

external_ref
string (ExternalRef)

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

object

the Project this Order belongs to, alternative to project_id property

object

the Warehouse of the Order, alternative to warehouse_id property

object

the Item produced by this Order, alternative to item_id property

object

the Relation of the Order, alternative to relation_id property

object or null

the delivery address for the order

Array of uuid (string) or Row Object with id (object)

optional Order Rows this Order supplies to, read Supplies and Receives for more information

Responses

Request samples

Content type
application/json
{
  • "type": "Sales",
  • "code": "S00235",
  • "description": "Furniture plot no 180",
  • "quantity": 42,
  • "external_url": "https://www.example.nl/url",
  • "sub_type": "precalculation",
  • "status": "foo",
  • "note": "Paint colors:\nInner: 4344-R58B\nOuter: S 0585-Y80R\n",
  • "contact": "John Doe",
  • "relation_ref": "CU1701246",
  • "date": "2020-05-02",
  • "desired_date": "2020-05-15",
  • "promised_date": "2020-05-22",
  • "delivered_date": "2020-05-14",
  • "collection_id": "60df67b0-aff3-4212-904c-46a42ea6d6f6",
  • "item_id": "25e01e69-57d2-4331-b1ca-5e13c0c99612",
  • "project_id": "5a6b204f-4b03-4f00-b0d8-3a6449b07040",
  • "relation_id": "401f7e85-af41-4d03-9c07-13cb7d1a4ea7",
  • "warehouse_id": "b006d5fd-b5f1-45c5-94bd-f60a50b79771",
  • "external_ref": "fb1033a2ed70",
  • "project": {
    • "id": "5a6b204f-4b03-4f00-b0d8-3a6449b07040"
    },
  • "warehouse": {
    • "id": "b006d5fd-b5f1-45c5-94bd-f60a50b79771"
    },
  • "item": {
    • "id": "25e01e69-57d2-4331-b1ca-5e13c0c99612"
    },
  • "relation": {
    • "id": "401f7e85-af41-4d03-9c07-13cb7d1a4ea7"
    },
  • "address": {
    • "street1": "Putman Cramerstraat 51a",
    • "street2": "first floor",
    • "postcode": "7468 BH",
    • "city": "Enter",
    • "state": "Overijssel",
    • "country": "Netherlands",
    • "latitude": 52.3156048,
    • "longitude": 6.496432
    },
  • "suppliesOrderRows": [
    • "194ab6b2-08f5-4403-9fb9-916f33c145bc"
    ]
}

Response samples

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

Remove Single Order

Remove a single Order

This will also remove the Collection created from this Order.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
order_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 28c8f918-f461-4a9c-9108-6bde41b4623e

The Order ID

Responses

Response samples

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

Address

There is no direct endpoint for interacting with an Address.

Address can be added or changed via the Order object. The Address can be removed from an Order by setting the Address object to null.

Because of geo coordinates a unique address (street1, street2, postcode, city, state and country) is only stored once, and can be attached to multiple orders. Updating the geo coordinates will update them for all orders.

id
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
street1
string
street2
string
postcode
string
city
string
state
string
country
string
hash
string

hash based on the trimmed values of street1, street2, postcode, city, state and country

internally used in case latitude and longitude are not given but already know

latitude
number

the geographic coordinate that specifies the north–south position

longitude
number

the geographic coordinate that specifies the east-west position

{
  • "id": "4a8482f0-0348-4551-9255-2c3a8ac425b8",
  • "street1": "Putman Cramerstraat 51a",
  • "street2": "first floor",
  • "postcode": "7468 BH",
  • "city": "Enter",
  • "state": "Overijssel",
  • "country": "Netherlands",
  • "hash": "2ee8ceab31952d603682752d4bde0c259ba8081ed6c755f73081ce9462530b5b",
  • "latitude": 52.3156048,
  • "longitude": 6.496432
}

Row

Endpoint to retrieve the order rows for a specific order. OrderRows could also be included in the order object.

Retrieve OrderRow List

Retrieve the OrderRow List

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
order_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 28c8f918-f461-4a9c-9108-6bde41b4623e

The Order 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: "suppliesOrderRows" "receivesOrderRows" "receivesOrder"

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

Possible options are:

  • suppliesOrderRows - (Purchase) Order Row that supplies to Rows of other Orders
  • receivesOrderRows - (Production / Sales) Order Rows that receive from (Purchase) Rows
  • receivesOrder - (Production / Sales) Order Rows that receive from (Production) Orders

deprecated

These includes are considered deprecated, and will be removed in the future. Use the equivalent with snake_case option (e.g. supplies_order_rows).

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

Response samples

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

Create New OrderRow

Create a new OrderRow and store it

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
order_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 28c8f918-f461-4a9c-9108-6bde41b4623e

The Order 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

Order to create

description
required
string
unit
required
string

unit type, use minutes, hours or days for activities

item_id
string <uuid>

id for the Item used

activity_id
string <uuid>

id for the Activity to be performed

external_ref
string (ExternalRef)

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

transaction
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
resource_ref
string

Third-party reference of the resource for this row, for informational purposes only

position
integer >= 0

position of the row in the list of order rows, used for sorting in frontend

code
string
type
string

reserved for future use

quantity
number <double>

quantity of the row, activity and unit are required for time calcuation

quantity_delivered
number <double>
quantity_backorder
number <double>
quantity_original
number <double>

for informational purposes only

status
string

reserved for future use

delivered_date
string <date-time>

delivery date of the row. Reserved for future use

object

the Item used by this Row, alternative to item_id property

object

the Activity to be performed, alternative to activity_id property

Array of uuid (string) or Row Object with id (object)

optional Order Rows this Row supplies to, read Supplies and Receives for more information

Array of uuid (string) or Row Object with id (object)

optional Order Rows this Row receives from, read Supplies and Receives for more information

Array of uuid (string) or Row Object with id (object)

optional Order this Row receives from, read Supplies and Receives for more information

Responses

Request samples

Content type
application/json
{
  • "item_id": "28c8f918-f461-4a9c-9108-6bde41b4623e",
  • "activity_id": "edebdb9d-fa39-4424-99b9-c5415ba9b24a",
  • "external_ref": "fb1033a2ed70",
  • "transaction": "587261f5-0fb7-4de0-bfdf-129b62a1e0a6",
  • "resource_ref": "640ye52oiwpa",
  • "position": 1,
  • "code": "A200",
  • "type": "foo",
  • "description": "Board 180",
  • "unit": "Piece",
  • "quantity": 42,
  • "quantity_delivered": 3,
  • "quantity_backorder": 39,
  • "quantity_original": 49,
  • "status": "foo",
  • "delivered_date": "2020-08-31",
  • "item": {
    • "id": "25e01e69-57d2-4331-b1ca-5e13c0c99612"
    },
  • "activity": {
    • "id": "edebdb9d-fa39-4424-99b9-c5415ba9b24a"
    },
  • "suppliesOrderRows": [
    • "af8fc937-64f2-44dd-b70f-847b9a397199"
    ],
  • "receivesOrderRows": [
    • "c40a10f3-d13c-401f-bf40-36b78061cbc4"
    ],
  • "receivesOrder": [
    • "be92293a-9436-46a9-bc46-6542896bf955"
    ]
}

Response samples

Content type
application/json
{
  • "item_id": "28c8f918-f461-4a9c-9108-6bde41b4623e",
  • "activity_id": "edebdb9d-fa39-4424-99b9-c5415ba9b24a",
  • "external_ref": "fb1033a2ed70",
  • "transaction": "587261f5-0fb7-4de0-bfdf-129b62a1e0a6",
  • "resource_ref": "640ye52oiwpa",
  • "position": 1,
  • "code": "A200",
  • "type": "foo",
  • "description": "Board 180",
  • "unit": "Piece",
  • "reserved": 15,
  • "quantity": 42,
  • "quantity_delivered": 3,
  • "quantity_backorder": 39,
  • "quantity_original": 49,
  • "status": "foo",
  • "delivered_date": "2020-08-31"
}

Retrieve Single OrderRow

Retrieve a single OrderRow from the order

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
order_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 28c8f918-f461-4a9c-9108-6bde41b4623e

The Order ID

row_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: d08abb79-6905-4917-a604-e8e39662e331

The Order Row 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: "suppliesOrderRows" "receivesOrderRows" "receivesOrder"

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

Possible options are:

  • suppliesOrderRows - (Purchase) Order Row that supplies to Rows of other Orders
  • receivesOrderRows - (Production / Sales) Order Rows that receive from (Purchase) Rows
  • receivesOrder - (Production / Sales) Order Rows that receive from (Production) Orders

deprecated

These includes are considered deprecated, and will be removed in the future. Use the equivalent with snake_case option (e.g. supplies_order_rows).

with
Array of strings
Items Enum: "activity" "item" "order" "supplies_order_rows" "receives_order_rows" "receives_order"

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

item_id
string <uuid>

id for the Item used

activity_id
string <uuid>

id for the Activity to be performed

external_ref
string (ExternalRef)

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

transaction
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
resource_ref
string

Third-party reference of the resource for this row, for informational purposes only

position
integer >= 0

position of the row in the list of order rows, used for sorting in frontend

code
string
type
string

reserved for future use

description
string
unit
string

unit type, use minutes, hours or days for activities

reserved
number <double>

deprecated calculated quantity of reserved items. Internally maintained, production order only

quantity
number <double>

quantity of the row, activity and unit are required for time calcuation

quantity_delivered
number <double>
quantity_backorder
number <double>
quantity_original
number <double>

for informational purposes only

status
string

reserved for future use

delivered_date
string <date-time>

delivery date of the row. Reserved for future use

order_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "id": "d08abb79-6905-4917-a604-e8e39662e331",
  • "item_id": "28c8f918-f461-4a9c-9108-6bde41b4623e",
  • "activity_id": "edebdb9d-fa39-4424-99b9-c5415ba9b24a",
  • "external_ref": "fb1033a2ed70",
  • "transaction": "587261f5-0fb7-4de0-bfdf-129b62a1e0a6",
  • "resource_ref": "640ye52oiwpa",
  • "position": 1,
  • "code": "A200",
  • "type": "foo",
  • "description": "Board 180",
  • "unit": "Piece",
  • "reserved": 15,
  • "quantity": 42,
  • "quantity_delivered": 3,
  • "quantity_backorder": 39,
  • "quantity_original": 49,
  • "status": "foo",
  • "delivered_date": "2020-08-31",
  • "order_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single OrderRow

Update a single OrderRow

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
order_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 28c8f918-f461-4a9c-9108-6bde41b4623e

The Order ID

row_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: d08abb79-6905-4917-a604-e8e39662e331

The Order Row ID

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

id for the Item used

activity_id
string <uuid>

id for the Activity to be performed

external_ref
string (ExternalRef)

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

transaction
string <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
resource_ref
string

Third-party reference of the resource for this row, for informational purposes only

position
integer >= 0

position of the row in the list of order rows, used for sorting in frontend

code
string
type
string

reserved for future use

description
string
unit
string

unit type, use minutes, hours or days for activities

quantity
number <double>

quantity of the row, activity and unit are required for time calcuation

quantity_delivered
number <double>
quantity_backorder
number <double>
quantity_original
number <double>

for informational purposes only

status
string

reserved for future use

delivered_date
string <date-time>

delivery date of the row. Reserved for future use

object

the Item used by this Row, alternative to item_id property

object

the Activity to be performed, alternative to activity_id property

Array of uuid (string) or Row Object with id (object)

optional Order Rows this Row supplies to, read Supplies and Receives for more information

Array of uuid (string) or Row Object with id (object)

optional Order Rows this Row receives from, read Supplies and Receives for more information

Array of uuid (string) or Row Object with id (object)

optional Order this Row receives from, read Supplies and Receives for more information

Responses

Request samples

Content type
application/json
{
  • "item_id": "28c8f918-f461-4a9c-9108-6bde41b4623e",
  • "activity_id": "edebdb9d-fa39-4424-99b9-c5415ba9b24a",
  • "external_ref": "fb1033a2ed70",
  • "transaction": "587261f5-0fb7-4de0-bfdf-129b62a1e0a6",
  • "resource_ref": "640ye52oiwpa",
  • "position": 1,
  • "code": "A200",
  • "type": "foo",
  • "description": "Board 180",
  • "unit": "Piece",
  • "quantity": 42,
  • "quantity_delivered": 3,
  • "quantity_backorder": 39,
  • "quantity_original": 49,
  • "status": "foo",
  • "delivered_date": "2020-08-31",
  • "item": {
    • "id": "25e01e69-57d2-4331-b1ca-5e13c0c99612"
    },
  • "activity": {
    • "id": "edebdb9d-fa39-4424-99b9-c5415ba9b24a"
    },
  • "suppliesOrderRows": [
    • "af8fc937-64f2-44dd-b70f-847b9a397199"
    ],
  • "receivesOrderRows": [
    • "c40a10f3-d13c-401f-bf40-36b78061cbc4"
    ],
  • "receivesOrder": [
    • "be92293a-9436-46a9-bc46-6542896bf955"
    ]
}

Response samples

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

Remove Single OrderRow

Remove a single OrderRow

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
order_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 28c8f918-f461-4a9c-9108-6bde41b4623e

The Order ID

row_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: d08abb79-6905-4917-a604-e8e39662e331

The Order Row ID

Responses

Response samples

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

Supplies and Receives

note

The concept of Order Rows supplying and receiving can be a little confusing at first.
If you are starting with a new integration, it is probably best to skip this level of complication at the beginning.

The goal of supplies and receives is to indicate the relation between orders.
This is purely a visual aid, and does not create any blocking or trigger mechanism.

Supplies and receives are presentations of the same data, where receives is simply the reserve of supplies. Most partners use supplies to create the relation with other Orders.

Abstractly seen in vPlan:

  • Order supplies to 0 or more Order Rows.
  • Order Row supplies to 0 or more Order Rows.
  • Order Row receives from 0 or more Orders or 0 or more Order Rows.

Logically that boils down to:

Sales Order Rows could receive from Purchase Order Rows or Production Orders.

Production Order (head) could supply to Sales Order Rows or Order Rows of other Production Orders.
Production Order Rows could receive from Purchase Order Rows or other Production Orders.

Purchase Order Rows could supply to Sales Order Rows and Production Order Rows.

Validations:

Please note that the previous is purely what normally would make sense, in theory a Sales Order Rows could simply supply Rows. There are no checks based on the Order type.

There is however the validation that a Row cannot supply itself or Rows that are within the same Order.

Project

A project is a series of activities and tasks. A project can be an umbrella for multiple orders, like sales and purchase orders.

Retrieve Project List

Retrieve the Project 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 (Project)

Response samples

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

Create New Project

Create a new Project 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

Project to create

name
required
string
code
string
description
string
external_ref
string (ExternalRef)

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

Responses

Request samples

Content type
application/json
{
  • "name": "Project Goliath",
  • "code": "GOL",
  • "description": "Building project up north",
  • "external_ref": "fb1033a2ed70"
}

Response samples

Content type
application/json
{
  • "id": "5a6b204f-4b03-4f00-b0d8-3a6449b07040",
  • "name": "Project Goliath",
  • "code": "GOL",
  • "description": "Building project up north",
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Single Project

Retrieve a single Project

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
project_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 5a6b204f-4b03-4f00-b0d8-3a6449b07040

The Project 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

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
code
string
description
string
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

Response samples

Content type
application/json
{
  • "id": "5a6b204f-4b03-4f00-b0d8-3a6449b07040",
  • "name": "Project Goliath",
  • "code": "GOL",
  • "description": "Building project up north",
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single Project

Update a single Project

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
project_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 5a6b204f-4b03-4f00-b0d8-3a6449b07040

The Project ID

Request Body schema: application/json
required
name
required
string
code
string
description
string
external_ref
string (ExternalRef)

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

Responses

Request samples

Content type
application/json
{
  • "name": "Project Goliath",
  • "code": "GOL",
  • "description": "Building project up north",
  • "external_ref": "fb1033a2ed70"
}

Response samples

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

Remove Single Project

Remove a single Project

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
project_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 5a6b204f-4b03-4f00-b0d8-3a6449b07040

The Project ID

Responses

Response samples

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

Relation

Relations provide contact information to orders.

Retrieve Relation List

Retrieve the Relation 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 (Relation)

Response samples

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

Create New Relation

Create a new Relation 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

Relation to create

name
required
string
type
string (Type)
Enum: "Production" "Project" "Purchase" "Quotation" "Sales"
description
string
note
string
phone
string
fax
string
email
string <email>
website
string <uri>
external_ref
string (ExternalRef)

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

Responses

Request samples

Content type
application/json
{
  • "name": "Example Company",
  • "type": "Sales",
  • "description": "Company that produces examples",
  • "note": "Great company\nSales Contact is Michel\n",
  • "phone": "+31 123 456 789",
  • "fax": "+31 123 456 799",
  • "email": "info@example.com",
  • "website": "www.example.com",
  • "external_ref": "fb1033a2ed70"
}

Response samples

Content type
application/json
{
  • "id": "401f7e85-af41-4d03-9c07-13cb7d1a4ea7",
  • "name": "Example Company",
  • "type": "Sales",
  • "description": "Company that produces examples",
  • "note": "Great company\nSales Contact is Michel\n",
  • "phone": "+31 123 456 789",
  • "fax": "+31 123 456 799",
  • "email": "info@example.com",
  • "website": "www.example.com",
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Single Relation

Retrieve a single Relation

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
relation_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 401f7e85-af41-4d03-9c07-13cb7d1a4ea7

The Relation 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

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
type
string (Type)
Enum: "Production" "Project" "Purchase" "Quotation" "Sales"
description
string
note
string
phone
string
fax
string
email
string <email>
website
string <uri>
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

Response samples

Content type
application/json
{
  • "id": "401f7e85-af41-4d03-9c07-13cb7d1a4ea7",
  • "name": "Example Company",
  • "type": "Sales",
  • "description": "Company that produces examples",
  • "note": "Great company\nSales Contact is Michel\n",
  • "phone": "+31 123 456 789",
  • "fax": "+31 123 456 799",
  • "email": "info@example.com",
  • "website": "www.example.com",
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single Relation

Update a single Relation

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
relation_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 401f7e85-af41-4d03-9c07-13cb7d1a4ea7

The Relation ID

Request Body schema: application/json
required
name
required
string
type
string (Type)
Enum: "Production" "Project" "Purchase" "Quotation" "Sales"
description
string
note
string
phone
string
fax
string
email
string <email>
website
string <uri>
external_ref
string (ExternalRef)

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

Responses

Request samples

Content type
application/json
{
  • "name": "Example Company",
  • "type": "Sales",
  • "description": "Company that produces examples",
  • "note": "Great company\nSales Contact is Michel\n",
  • "phone": "+31 123 456 789",
  • "fax": "+31 123 456 799",
  • "email": "info@example.com",
  • "website": "www.example.com",
  • "external_ref": "fb1033a2ed70"
}

Response samples

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

Remove Single Relation

Remove a single Relation

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
relation_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 401f7e85-af41-4d03-9c07-13cb7d1a4ea7

The Relation ID

Responses

Response samples

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

Resource

Resources are employees, machines or cells. Every resource has a schedule for availability. A resource can be assigned to multiple cards.

note The avatar is provided to this API using data URI scheme, the avatar is processed and uploaded as a static image to https://fs.mostwanted.io. The return value is a URL.

It is not possible to provided a custom URL.

warning An update of a resource will always trigger an async process to rebuild all schedules for that resource.

Any manual changes made to the schedules between the start and end date of the resource will not persist

Retrieve Resource List

Retrieve the Resource 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: "activities" "cards" "groups" "schedules" "schedule_deviations"

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

Possible options are:

  • activities - activities the resource is able to perform
  • cards
  • groups - resource groups it belongs to
  • schedules
  • schedule_deviations

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

name
string
type
string (ResourceType)
Enum: "employee" "machine" "cell"
start_date
string <date>
object

Days of the week that are considered workdays

description
string
end_date
string <date>
integration_schedule
boolean

false vPlan manages the schedules via workdays, true integration manages the schedules

avatar
string
color_hex
string^#[0-9a-f]$

color hex is used to signify the Resource, only used if the avatar is null

external_ref
string (ExternalRef)

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

archived_at
string <date-time>

date / time that the object is archived

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "id": "a225c108-a6ca-4343-8e10-fe10c841a688",
  • "name": "John Doe",
  • "type": "employee",
  • "start_date": "2020-01-01",
  • "workdays": {
    • "1": 8,
    • "2": 8.2,
    • "3": 4.5,
    • "4": 7.88,
    • "5": 8,
    • "6": 0,
    • "7": 0
    },
  • "description": "Master wood engraver",
  • "end_date": "2020-12-31",
  • "integration_schedule": false,
  • "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "color_hex": "#e0527c",
  • "external_ref": "fb1033a2ed70",
  • "archived_at": "2021-07-06T11:24:35Z",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Create New Resource

Create a new Resource 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

Resource to create

name
required
string
type
string (ResourceType)
Enum: "employee" "machine" "cell"
start_date
string <date>
object

Days of the week that are considered workdays

description
string
end_date
string <date>
integration_schedule
boolean

false vPlan manages the schedules via workdays, true integration manages the schedules

avatar
string
color_hex
string^#[0-9a-f]$

color hex is used to signify the Resource, only used if the avatar is null

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
{
  • "name": "John Doe",
  • "type": "employee",
  • "start_date": "2020-01-01",
  • "workdays": {
    • "1": 8,
    • "2": 8.2,
    • "3": 4.5,
    • "4": 7.88,
    • "5": 8,
    • "6": 0,
    • "7": 0
    },
  • "description": "Master wood engraver",
  • "end_date": "2020-12-31",
  • "integration_schedule": false,
  • "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "color_hex": "#e0527c",
  • "external_ref": "fb1033a2ed70",
  • "archive": false
}

Response samples

Content type
application/json
{
  • "id": "a225c108-a6ca-4343-8e10-fe10c841a688",
  • "name": "John Doe",
  • "type": "employee",
  • "start_date": "2020-01-01",
  • "workdays": {
    • "1": 8,
    • "2": 8.2,
    • "3": 4.5,
    • "4": 7.88,
    • "5": 8,
    • "6": 0,
    • "7": 0
    },
  • "description": "Master wood engraver",
  • "end_date": "2020-12-31",
  • "integration_schedule": false,
  • "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "color_hex": "#e0527c",
  • "external_ref": "fb1033a2ed70",
  • "archived_at": "2021-07-06T11:24:35Z",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Single Resource

Retrieve a single Resource

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
resource_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a225c108-a6ca-4343-8e10-fe10c841a688

The Resource 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: "activities" "cards" "groups" "schedules" "schedule_deviations"

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

Possible options are:

  • activities - activities the resource is able to perform
  • cards
  • groups - resource groups it belongs to
  • schedules
  • schedule_deviations

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
type
string (ResourceType)
Enum: "employee" "machine" "cell"
start_date
string <date>
object

Days of the week that are considered workdays

description
string
end_date
string <date>
integration_schedule
boolean

false vPlan manages the schedules via workdays, true integration manages the schedules

avatar
string
color_hex
string^#[0-9a-f]$

color hex is used to signify the Resource, only used if the avatar is null

external_ref
string (ExternalRef)

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

archived_at
string <date-time>

date / time that the object is archived

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "id": "a225c108-a6ca-4343-8e10-fe10c841a688",
  • "name": "John Doe",
  • "type": "employee",
  • "start_date": "2020-01-01",
  • "workdays": {
    • "1": 8,
    • "2": 8.2,
    • "3": 4.5,
    • "4": 7.88,
    • "5": 8,
    • "6": 0,
    • "7": 0
    },
  • "description": "Master wood engraver",
  • "end_date": "2020-12-31",
  • "integration_schedule": false,
  • "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "color_hex": "#e0527c",
  • "external_ref": "fb1033a2ed70",
  • "archived_at": "2021-07-06T11:24:35Z",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single Resource

Update a single Resource

warning An update of a resource will always trigger an async process to rebuild all schedules for that resource. Any manual changes made to the schedules between the start and end date of the resource will not persist

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
resource_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a225c108-a6ca-4343-8e10-fe10c841a688

The Resource ID

Request Body schema: application/json
required
name
string
type
string (ResourceType)
Enum: "employee" "machine" "cell"
start_date
string <date>
object

Days of the week that are considered workdays

description
string
end_date
string <date>
integration_schedule
boolean

false vPlan manages the schedules via workdays, true integration manages the schedules

avatar
string
color_hex
string^#[0-9a-f]$

color hex is used to signify the Resource, only used if the avatar is null

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
{
  • "name": "John Doe",
  • "type": "employee",
  • "start_date": "2020-01-01",
  • "workdays": {
    • "1": 8,
    • "2": 8.2,
    • "3": 4.5,
    • "4": 7.88,
    • "5": 8,
    • "6": 0,
    • "7": 0
    },
  • "description": "Master wood engraver",
  • "end_date": "2020-12-31",
  • "integration_schedule": false,
  • "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
  • "color_hex": "#e0527c",
  • "external_ref": "fb1033a2ed70",
  • "archive": false
}

Response samples

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

Remove Single Resource

Remove a single Resource

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
resource_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a225c108-a6ca-4343-8e10-fe10c841a688

The Resource ID

Responses

Response samples

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

Schedule

Retrieve Schedule List

Retrieve the Schedule List

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
resource_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a225c108-a6ca-4343-8e10-fe10c841a688

The Resource 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

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_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
date
string <date>
hours_available
number <double>
hours_work
number <double>
hours_leave
number <double>
hours_absence
number <double>
created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "id": "b18c06cd-cc69-4b26-81de-04e78c4fd3b0",
  • "resource_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "date": "2020-10-19",
  • "hours_available": 8,
  • "hours_work": 8,
  • "hours_leave": 0,
  • "hours_absence": 0,
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Schedule Year

Retrieve the Schedule List for the given year

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
resource_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a225c108-a6ca-4343-8e10-fe10c841a688

The Resource ID

year
required
integer/^\d{4}$/
Example: 2020
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

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 (Schedule)

Response samples

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

Retrieve Schedule Month

Retrieve the Schedule List for the given year and month

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
resource_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a225c108-a6ca-4343-8e10-fe10c841a688

The Resource ID

year
required
integer/^\d{4}$/
Example: 2020
month
required
integer [ 1 .. 12 ] /^\d{2}$/
Example: 3
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

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 (Schedule)

Response samples

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

Schedule Retrieve Day

Retrieve the Schedule List for the given year, month and day

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
resource_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: a225c108-a6ca-4343-8e10-fe10c841a688

The Resource ID

year
required
integer/^\d{4}$/
Example: 2020
month
required
string [ 1 .. 12 ] /^\d{2}$/
Example: 3
day
required
string [ 1 .. 31 ] /^\d{2}$/
Example: 9
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

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 (Schedule)

Response samples

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

Affiliation to Resource

Most integrations that create Resources want to relate the Time Tracking with those resources.

One important note regarding this:
Time Tracking does not have a direct relation to a resource.

However there is a indirect relation, a few things to take in account:

  • a time tracking typically has a user
  • a user is optionally linked to a resource
  • a resource can be linked to multiple users

By retrieving Time Tracking with user.resource it may be possible to connect a Time Tracking to a resource. This link is optional, thus it is possible no resource is returned.

In addition, make sure that the customer has set up their users correctly.

See Difference between resources and users in our support documentation.

Time Tracking

Time Tracking is used to keep track of the activities that a user has done. There are 2 options to store time

  • use start and end (datetime)
  • use duration and start (datetime)

Retrieve TimeTracking List

Retrieve the TimeTracking List for this card

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

with
Array of strings
Items Enum: "card" "user" "user.resource" "activity"

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
card_id
string <uuid> (IdReadOnly) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

The id of the card connected to this Time Tracking

When time tracking is in draft, the card_id can be null. This indicates a user started time tracking without specifying an card yet.

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

Unique identifier

start
string <date-time>

Start date and time of time tracking row

end
string <date-time>

End date and time of time tracking row

duration
integer

the duration in minutes

status
string
Default: "draft"
Enum: "draft" "pending" "approved" "rejected"

Status of TimeTracking.

For the user role Worker only draft and pending are allowed

note

card_id must be set if status is not draft

activity_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
user_id
string or null <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

The user that performed the activity for which the time is tracked

If not given the current user will be used

Can be null if the user is deleted

note
string

note from an end-user

locked
boolean

Locks the Time Tracking for futher changes, only a user with the Administrator role can change this value from true to false

synchronized_at
string <date-time>

Third-party property to show the last synchronization

external_ref
string (ExternalRef)

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

external_note
string

Third-party note that is read-only for an end-user

external_failed
boolean
Default: false

Third-party indicator of a processing error

running
boolean

signifies that a Time Tracking was started but not yet ended

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "card_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "id": "acaa8748-1a37-4581-bd22-3d7646767723",
  • "start": "2020-01-02T11:24:35Z",
  • "end": "2020-01-02T11:34:35Z",
  • "duration": 120,
  • "status": "draft",
  • "activity_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "user_id": "10e61b05-d504-4bba-9894-415e6114cb79",
  • "note": "string",
  • "locked": true,
  • "synchronized_at": "2019-08-24T14:15:22Z",
  • "external_ref": "fb1033a2ed70",
  • "external_note": "Reason for rejection - Hours are way too much",
  • "external_failed": true,
  • "running": true,
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Create New TimeTracking

Create a new TimeTracking and store it for this collection

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

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

TimeTracking to create

activity_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
start
required
string <date-time>

Start date and time of time tracking row

card_id
string or null <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

The id of the card connected to this Time Tracking

When time tracking is in draft, the card_id can be null. This indicates a user started time tracking without specifying an card yet. To change the status from draft to anything else, a card needs to be chosen.

note

Once a card_id is set it cannot be changed

end
string <date-time>

End date and time of time tracking row

duration
integer

the duration in minutes

status
string
Default: "draft"
Enum: "draft" "pending" "approved" "rejected"

Status of TimeTracking.

For the user role Worker only draft and pending are allowed

note

card_id must be set if status is not draft

user_id
string or null <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

The user that performed the activity for which the time is tracked

If not given the current user will be used

Can be null if the user is deleted

note
string

note from an end-user

locked
boolean

Locks the Time Tracking for futher changes, only a user with the Administrator role can change this value from true to false

synchronized_at
string <date-time>

Third-party property to show the last synchronization

external_ref
string (ExternalRef)

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

external_note
string

Third-party note that is read-only for an end-user

external_failed
boolean
Default: false

Third-party indicator of a processing error

Responses

Request samples

Content type
application/json
{
  • "card_id": "92f8fd27-2ddb-4ca4-b42a-610b9d0349c9",
  • "start": "2020-01-02T11:24:35Z",
  • "end": "2020-01-02T11:34:35Z",
  • "duration": 120,
  • "status": "draft",
  • "activity_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "user_id": "10e61b05-d504-4bba-9894-415e6114cb79",
  • "note": "string",
  • "locked": true,
  • "synchronized_at": "2019-08-24T14:15:22Z",
  • "external_ref": "fb1033a2ed70",
  • "external_note": "Reason for rejection - Hours are way too much",
  • "external_failed": true
}

Response samples

Content type
application/json
{
  • "card_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "id": "acaa8748-1a37-4581-bd22-3d7646767723",
  • "start": "2020-01-02T11:24:35Z",
  • "end": "2020-01-02T11:34:35Z",
  • "duration": 120,
  • "status": "draft",
  • "activity_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "user_id": "10e61b05-d504-4bba-9894-415e6114cb79",
  • "note": "string",
  • "locked": true,
  • "synchronized_at": "2019-08-24T14:15:22Z",
  • "external_ref": "fb1033a2ed70",
  • "external_note": "Reason for rejection - Hours are way too much",
  • "external_failed": true,
  • "running": true,
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Single TimeTracking

Retrieve a single TimeTracking from this collection

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
time_tracking_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 1a092203-8cb4-4fa8-9428-19d8d49b714a

The TimeTracking 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: "card" "user" "user.resource" "activity"

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
card_id
string <uuid> (IdReadOnly) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

The id of the card connected to this Time Tracking

When time tracking is in draft, the card_id can be null. This indicates a user started time tracking without specifying an card yet.

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

Unique identifier

start
string <date-time>

Start date and time of time tracking row

end
string <date-time>

End date and time of time tracking row

duration
integer

the duration in minutes

status
string
Default: "draft"
Enum: "draft" "pending" "approved" "rejected"

Status of TimeTracking.

For the user role Worker only draft and pending are allowed

note

card_id must be set if status is not draft

activity_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
user_id
string or null <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

The user that performed the activity for which the time is tracked

If not given the current user will be used

Can be null if the user is deleted

note
string

note from an end-user

locked
boolean

Locks the Time Tracking for futher changes, only a user with the Administrator role can change this value from true to false

synchronized_at
string <date-time>

Third-party property to show the last synchronization

external_ref
string (ExternalRef)

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

external_note
string

Third-party note that is read-only for an end-user

external_failed
boolean
Default: false

Third-party indicator of a processing error

running
boolean

signifies that a Time Tracking was started but not yet ended

created_at
string <date-time>

Creation date / time

updated_at
string <date-time>

Update date / time

Response samples

Content type
application/json
{
  • "card_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "id": "acaa8748-1a37-4581-bd22-3d7646767723",
  • "start": "2020-01-02T11:24:35Z",
  • "end": "2020-01-02T11:34:35Z",
  • "duration": 120,
  • "status": "draft",
  • "activity_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "user_id": "10e61b05-d504-4bba-9894-415e6114cb79",
  • "note": "string",
  • "locked": true,
  • "synchronized_at": "2019-08-24T14:15:22Z",
  • "external_ref": "fb1033a2ed70",
  • "external_note": "Reason for rejection - Hours are way too much",
  • "external_failed": true,
  • "running": true,
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single TimeTracking

Update a single TimeTracking

The current status of a Time Tracking determines what is allowed to be updated.

A locked Time Tracking can only be unlocked by a user with the role Administrator. A user with the role Worker can only update a Time Tracking with the status draft or rejected.

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
time_tracking_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 1a092203-8cb4-4fa8-9428-19d8d49b714a

The TimeTracking ID

Request Body schema: application/json
required
One of
card_id
string or null <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

The id of the card connected to this Time Tracking

When time tracking is in draft, the card_id can be null. This indicates a user started time tracking without specifying an card yet. To change the status from draft to anything else, a card needs to be chosen.

note

Once a card_id is set it cannot be changed

start
string <date-time>

Start date and time of time tracking row

end
string <date-time>

End date and time of time tracking row

duration
integer

the duration in minutes

status
string
Default: "draft"
Enum: "draft" "pending" "approved" "rejected"

Status of TimeTracking.

For the user role Worker only draft and pending are allowed

note

card_id must be set if status is not draft

activity_id
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
user_id
string or null <uuid> /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...

The user that performed the activity for which the time is tracked

If not given the current user will be used

Can be null if the user is deleted

note
string

note from an end-user

locked
boolean

Locks the Time Tracking for futher changes, only a user with the Administrator role can change this value from true to false

synchronized_at
string <date-time>

Third-party property to show the last synchronization

external_ref
string (ExternalRef)

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

external_note
string

Third-party note that is read-only for an end-user

external_failed
boolean
Default: false

Third-party indicator of a processing error

Responses

Request samples

Content type
application/json
Example
{
  • "card_id": "92f8fd27-2ddb-4ca4-b42a-610b9d0349c9",
  • "start": "2020-01-02T11:24:35Z",
  • "end": "2020-01-02T11:34:35Z",
  • "duration": 120,
  • "status": "draft",
  • "activity_id": "f189bd17-445d-4d78-84ba-b8d845305121",
  • "user_id": "10e61b05-d504-4bba-9894-415e6114cb79",
  • "note": "string",
  • "locked": true,
  • "synchronized_at": "2019-08-24T14:15:22Z",
  • "external_ref": "fb1033a2ed70",
  • "external_note": "Reason for rejection - Hours are way too much",
  • "external_failed": true
}

Response samples

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

Remove Single TimeTracking

Remove a single TimeTracking

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
time_tracking_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: 1a092203-8cb4-4fa8-9428-19d8d49b714a

The TimeTracking ID

Responses

Response samples

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

Warehouse

A warehouse is a location where items are stored. An order is always related to a warehouse, as a result, creating at least one warehouse is required.

Retrieve Warehouse List

Retrieve the Warehouse 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 (Warehouse)

Response samples

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

Create New Warehouse

Create a new Warehouse 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

Warehouse to create

code
string
name
string
external_ref
string (ExternalRef)

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

Responses

Request samples

Content type
application/json
{
  • "code": "EN",
  • "name": "Depot Enter (NL)",
  • "external_ref": "fb1033a2ed70"
}

Response samples

Content type
application/json
{
  • "id": "b006d5fd-b5f1-45c5-94bd-f60a50b79771",
  • "code": "EN",
  • "name": "Depot Enter (NL)",
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Single Warehouse

Retrieve a single Warehouse

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
warehouse_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: b006d5fd-b5f1-45c5-94bd-f60a50b79771

The Warehouse 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

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

code
string
name
string
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

Response samples

Content type
application/json
{
  • "id": "b006d5fd-b5f1-45c5-94bd-f60a50b79771",
  • "code": "EN",
  • "name": "Depot Enter (NL)",
  • "external_ref": "fb1033a2ed70",
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single Warehouse

Update a single Warehouse

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
warehouse_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: b006d5fd-b5f1-45c5-94bd-f60a50b79771

The Warehouse ID

Request Body schema: application/json
required
code
string
name
string
external_ref
string (ExternalRef)

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

Responses

Request samples

Content type
application/json
{
  • "code": "EN",
  • "name": "Depot Enter (NL)",
  • "external_ref": "fb1033a2ed70"
}

Response samples

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

Remove Single Warehouse

Remove a single Warehouse

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
warehouse_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: b006d5fd-b5f1-45c5-94bd-f60a50b79771

The Warehouse ID

Responses

Response samples

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

Webhook

Webhooks can be used to get a signal from our servers if a certain event is triggered.

Instead of retrieving objects for example every 30 minutes, and looking for changes. Webhooks can be used to receive a signal when an action is performed.

There is a wide variety of triggers available.

A webhook can be manually set up via Settings -> Developers in the vPlan web frontend.
Or added programmatically via the POST /webhook

Note

We strongly suggest that you respond with a 2xx HTTP status code immediately after receiving the message and handle all other tasks afterward.

Think of it like parcel delivery, if you were to drop off a parcel at the service point, they would issue a receipt stating that the parcel is being sent. They don't make you wait for the recipient to receive and use the package.

Retrieve Webhook List

Retrieve the Webhook 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 (Webhook)

Response samples

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

Create New Webhook

Create a new Webhook 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

Webhook to create

url
required
string <uri> ^https://.+

the url where the event is send to

note

this url must be publically available

self signed certificates are not supported

description
string
active
boolean
Array of Normal Object (string) or Nested Object (string) or Nested Object with Pivot (string)

array of all event that are send to the url

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "bf10a807-7583-47e6-aa6a-70e0313d81b0",
  • "url": "https://example.com/webhook",
  • "description": "string",
  • "active": true,
  • "api_key_id": "b0dd218e-3bcf-4bdb-a1e3-0689d60a8afd",
  • "developer_client_id": "edacd88b-ac24-46ed-9e2e-107a147f9d6c",
  • "event_types": [
    • "card.created"
    ],
  • "fail_streak": 363,
  • "fail_streak_started_at": "2022-02-15T15:32:05Z",
  • "last_failed_at": "2022-02-18T20:39:51Z",
  • "mailed_warning_at": "2022-02-15T16:33:07Z",
  • "mailed_disabled_at": null,
  • "disabled_until": null,
  • "third_party": true,
  • "can_send": true,
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Retrieve Single Webhook

Retrieve a single Webhook

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
webhook_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: bf10a807-7583-47e6-aa6a-70e0313d81b0

The Webhook 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

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

url
required
string <uri> ^https://.+

the url where the event is send to

note

this url must be publically available

self signed certificates are not supported

description
required
string
active
required
boolean
api_key_id
required
string or null <uuid>

if the webhook is created via an api key, the id of that api key is shown here

to look up your api_key id look at the /me endpoint

developer_client_id
required
string or null <uuid>

if the webhook is created via an oAuth connection, the client id of the oAuth app is shown here

required
Array of Normal Object (string) or Nested Object (string) or Nested Object with Pivot (string)

array of all event that are send to the url

third_party
required
boolean

true if the webhook is created via API Key or oAuth

created_at
required
string <date-time>

Creation date / time

updated_at
required
string <date-time>

Update date / time

fail_streak
integer or null

number of last consecutive failed attempts

fail_streak_started_at
string or null <date-time>

Date and time the current fail streak started

last_failed_at
string or null <date-time>

Date and time of the last failed attempt of the current fail streak

mailed_warning_at
string or null <date-time>

Date and time the warning mail was sent to the administrators

mailed_disabled_at
string or null <date-time>

Date and time the disabled notify mail was sent to the administrators

disabled_until
string or null <date-time>

Date and time indicating a temporarily disabled a webhook

can_send
boolean

false if the webhook had too many consecutive failed attempts or was temporarily disabled

when false events will be suspended and not send out automatically

Response samples

Content type
application/json
{
  • "id": "bf10a807-7583-47e6-aa6a-70e0313d81b0",
  • "url": "https://example.com/webhook",
  • "description": "string",
  • "active": true,
  • "api_key_id": "b0dd218e-3bcf-4bdb-a1e3-0689d60a8afd",
  • "developer_client_id": "edacd88b-ac24-46ed-9e2e-107a147f9d6c",
  • "event_types": [
    • "card.created"
    ],
  • "fail_streak": 363,
  • "fail_streak_started_at": "2022-02-15T15:32:05Z",
  • "last_failed_at": "2022-02-18T20:39:51Z",
  • "mailed_warning_at": "2022-02-15T16:33:07Z",
  • "mailed_disabled_at": null,
  • "disabled_until": null,
  • "third_party": true,
  • "can_send": true,
  • "created_at": "2020-01-02T11:24:35Z",
  • "updated_at": "2020-01-02T11:24:35Z"
}

Update Single Webhook

Update a single Webhook

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
webhook_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: bf10a807-7583-47e6-aa6a-70e0313d81b0

The Webhook ID

Request Body schema: application/json
required
url
string <uri> ^https://.+

the url where the event is send to

note

this url must be publically available

self signed certificates are not supported

description
string
active
boolean
Array of Normal Object (string) or Nested Object (string) or Nested Object with Pivot (string)

array of all event that are send to the url

Responses

Request samples

Content type
application/json
{}

Response samples

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

Remove Single Webhook

Remove a single Webhook

Authorizations:
JwtTokenOauth2(Api-KeyApi-Env)
path Parameters
webhook_id
required
string <uuid> (Id) /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8...
Example: bf10a807-7583-47e6-aa6a-70e0313d81b0

The Webhook ID

Responses

Response samples

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

Payload send to webhook url

Webhooks have 3 general result types:

Type Description
Normal objects either a Create, Update or Delete for objects like Card, Collection and Comment
Nested objects either an Attached or Detached object to a parent object like a Label or Resource attached to a Card or Collection
Nested objects with pivot values Same as Nested objects however with pivot values, like Activity attached to a Card with a time estimate of 60 minutes

Note

We strongly suggest that you respond with a 2xx HTTP status code immediately after receiving the message and handle all other tasks afterward.

Think of it like parcel delivery, if you were to drop off a parcel at the service point, they would issue a receipt stating that the parcel is being sent. They don't make you wait for the recipient to receive and use the package.

Normal Object Webhook

Request Body schema: application/json
required
environment
string

hash identifier unique per customer

trigger
string

Information about who or what triggered the event.

Normally this would be User:: followed by an id, events triggered by automations will have the value Bot::Automation.

Note

This property can be used to filter out webhooks that are triggered by actions performed by the integration it self.

Use the /me endpoint to lookup the user.id of the connection that is used.

event
string (WebhookEventNormal)
Enum: "card.created" "card.updated" "card.deleted" "card.updated.merged" "collection.created" "collection.updated" "collection.deleted" "attachment.created" "attachment.updated" "attachment.deleted" "comment.created" "comment.updated" "comment.deleted" "time_tracking.created" "time_tracking.updated" "time_tracking.deleted"

Possible events for a basic object

object

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "trigger": "string",
  • "event": "card.created",
  • "data": {
    • "new": { },
    • "old": { },
    • "current": { }
    }
}

Nested Object Webhook

Request Body schema: application/json
required
environment
string

hash identifier unique per customer

trigger
string

Information about who or what triggered the event.

Normally this would be User:: followed by an id, events triggered by automations will have the value Bot::Automation.

Note

This property can be used to filter out webhooks that are triggered by actions performed by the integration it self.

Use the /me endpoint to lookup the user.id of the connection that is used.

event
string (WebhookEventNested)
Enum: "card.label.attached" "card.label.detached" "card.resource.attached" "card.resource.detached" "collection.label.attached" "collection.label.detached" "collection.follower.attached" "collection.follower.detached"

Possible events for objects that are attached or detached to another object

object

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "trigger": "string",
  • "event": "card.label.attached",
  • "data": {
    • "attached": { },
    • "detached": { },
    • "current": { }
    }
}

Nested Object with Pivot Webhook

Request Body schema: application/json
required
environment
string

hash identifier unique per customer

trigger
string

Information about who or what triggered the event.

Normally this would be User:: followed by an id, events triggered by automations will have the value Bot::Automation.

Note

This property can be used to filter out webhooks that are triggered by actions performed by the integration it self.

Use the /me endpoint to lookup the user.id of the connection that is used.

event
string (WebhookEventNestedPivot)
Enum: "card.activity.attached" "card.activity.detached" "card.activity.updated" "collection.activity.attached" "collection.activity.detached" "collection.activity.updated" "collection.checklist.created" "collection.checklist.updated" "collection.checklist.deleted" "collection.checklist.item.attached" "collection.checklist.item.detached" "collection.checklist.item.updated"

Possible events for objects that are attached or detached to another object and have specific pivot values

e.g. the time and time_remaining for an Activity attached to a Card

object

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "trigger": "string",
  • "event": "card.activity.attached",
  • "data": {
    • "attached": { },
    • "detached": { },
    • "current": { },
    • "new": { },
    • "updated": { }
    }
}