Create New Collection

Create a new Collection and store it

Request

Query Params

show

string

optional

limit the response to show only specific properties, see show & hide for more info

Example:

hide

string

optional

hide properties from the response, see show & hide for more info

Example:

name

Header Params

x-api-key

string

required

Default:

x-api-env

string

required

Default:

Body Params application/json

name

string

optional

Example:

Order 10199

description

string | null

optional

Example:

3x Chair Lissabon

due_date

string <date> | null

optional

Example:

2020-01-02

custom_fields

array[object (CustomField) {10}]

required

name

string

optional

Name of the field

Example:

Weight

type

enum<string>

optional

Allowed values:

textnumberdatecheckboxemaillinkphonelistselectaddressdrawingtextareausers

Default:

text

Example:

number

scope

enum<string>

optional

Allowed values:

collectioncard

priority

integer

optional

Priority of the custom field in which the fields are ordered in the frontend

Example:

value

optional

drawing_id

string <uuid>

optional

components

object (CustomFieldOptionsAddress)

optional

list

array [object {3}]

optional

selected

object

optional

options

optional

Extra settings for number, select or list types

board_id

string <uuid>

required

Unique identifier of the Board

cover_image_url

string <uri> | null

optional

cover_image_checksum

string | null

write-onlyoptional

Match pattern:

^[a-fA-F0-9]{64}$

cover_color_hex

string | null

optional

Examples:

#FFF#8d46e0

Match pattern:

^#([A-Fa-f0-9]{3}){1,2}$

Example

{
  "name": "Order 10199",
  "description": "3x Chair Lissabon",
  "due_date": "2020-01-02",
  "custom_fields": [
    {
      "name": "Weight",
      "type": "number",
      "scope": "collection",
      "priority": 0,
      "value": "non officia incididunt commodo in",
      "drawing_id": "78036ec5-5487-decc-8723-98e37adda5c2",
      "components": {
        "latitude": 52.3156048,
        "longitude": 6.496432,
        "country": "Netherlands",
        "city": "Rijssen",
        "postal_code": "7462TB",
        "street1": "Hogepad 83",
        "street2": "Second floor"
      },
      "list": [
        {
          "name": "Opal Will-Kuhlman",
          "value": "officia sed non",
          "color": "brown"
        },
        {
          "name": "Claude Robel",
          "value": "Excepteur",
          "color": "raspberry"
        }
      ],
      "selected": {
        "name": "Rosie Hudson",
        "value": "commodo ex reprehenderit cillum",
        "color": "yellow"
      },
      "options": null
    },
    {
      "name": "Weight",
      "type": "number",
      "scope": "collection",
      "priority": 0,
      "value": {},
      "drawing_id": "f2fbc8dd-99d3-dc79-a87f-41b73b1f7cef",
      "components": {
        "latitude": 52.3156048,
        "longitude": 6.496432,
        "country": "Netherlands",
        "city": "Rijssen",
        "postal_code": "7462TB",
        "street1": "Hogepad 83",
        "street2": "Second floor"
      },
      "list": [
        {
          "name": "Mr. Marcos Kunze",
          "value": "deserunt",
          "color": "navy"
        },
        {
          "name": "Domingo Herzog",
          "value": "adipisicing",
          "color": "indigo"
        },
        {
          "name": "Jimmie Smitham",
          "value": "nisi sit",
          "color": "grey"
        }
      ],
      "selected": {
        "name": "Wilfred Casper",
        "value": "dolore",
        "color": "indigo"
      },
      "options": {
        "latitude": 52.3156048,
        "longitude": 6.496432,
        "country": "Netherlands",
        "city": "Rijssen",
        "postal_code": "7462TB",
        "street1": "Hogepad 83",
        "street2": "Second floor"
      }
    }
  ],
  "board_id": "f73fe9a6-4e4c-6c70-c36b-fa70737ef145",
  "cover_image_url": "https://loremflickr.com/400/400?lock=6413716204599029",
  "cover_image_checksum": "b4fbE3BAafC5AC23A1accb0AcCfAff74adf17Bd2201e9AE3B0AbcCD7793Ec0eB",
  "cover_color_hex": "#FFF"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.vplan.com/v1/collection' \
--header 'x-api-key;' \
--header 'x-api-env;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Order 10199",
    "description": "3x Chair Lissabon",
    "due_date": "2020-01-02",
    "custom_fields": [
        {
            "name": "Weight",
            "type": "number",
            "scope": "collection",
            "priority": 0,
            "value": "non officia incididunt commodo in",
            "drawing_id": "78036ec5-5487-decc-8723-98e37adda5c2",
            "components": {
                "latitude": 52.3156048,
                "longitude": 6.496432,
                "country": "Netherlands",
                "city": "Rijssen",
                "postal_code": "7462TB",
                "street1": "Hogepad 83",
                "street2": "Second floor"
            },
            "list": [
                {
                    "name": "Opal Will-Kuhlman",
                    "value": "officia sed non",
                    "color": "brown"
                },
                {
                    "name": "Claude Robel",
                    "value": "Excepteur",
                    "color": "raspberry"
                }
            ],
            "selected": {
                "name": "Rosie Hudson",
                "value": "commodo ex reprehenderit cillum",
                "color": "yellow"
            },
            "options": null
        },
        {
            "name": "Weight",
            "type": "number",
            "scope": "collection",
            "priority": 0,
            "value": {},
            "drawing_id": "f2fbc8dd-99d3-dc79-a87f-41b73b1f7cef",
            "components": {
                "latitude": 52.3156048,
                "longitude": 6.496432,
                "country": "Netherlands",
                "city": "Rijssen",
                "postal_code": "7462TB",
                "street1": "Hogepad 83",
                "street2": "Second floor"
            },
            "list": [
                {
                    "name": "Mr. Marcos Kunze",
                    "value": "deserunt",
                    "color": "navy"
                },
                {
                    "name": "Domingo Herzog",
                    "value": "adipisicing",
                    "color": "indigo"
                },
                {
                    "name": "Jimmie Smitham",
                    "value": "nisi sit",
                    "color": "grey"
                }
            ],
            "selected": {
                "name": "Wilfred Casper",
                "value": "dolore",
                "color": "indigo"
            },
            "options": {
                "latitude": 52.3156048,
                "longitude": 6.496432,
                "country": "Netherlands",
                "city": "Rijssen",
                "postal_code": "7462TB",
                "street1": "Hogepad 83",
                "street2": "Second floor"
            }
        }
    ],
    "board_id": "f73fe9a6-4e4c-6c70-c36b-fa70737ef145",
    "cover_image_url": "https://loremflickr.com/400/400?lock=6413716204599029",
    "cover_image_checksum": "b4fbE3BAafC5AC23A1accb0AcCfAff74adf17Bd2201e9AE3B0AbcCD7793Ec0eB",
    "cover_color_hex": "#FFF"
}'

Responses

🟢201Created

application/json

Body

string <uuid>

read-onlyoptional

Unique identifier

name

string

optional

Example:

Order 10199

description

string | null

optional

Example:

3x Chair Lissabon

start

string <date> | null

read-onlyoptional

Earliest date from its Cards

Example:

2020-01-02

end

string <date> | null

read-onlyoptional

Latest date from its Cards

Example:

2020-08-13

due_date

string <date> | null

optional

Example:

2020-01-02

meta

object | null

read-onlyoptional

Hashmap with additional information for the collection, received via Order

Example:

{"bar":"foo","baz":"quux"}

Additional properties

string

optional

position

integer | null

read-onlyoptional

Position in the backlog, if collection is planned the postion will be null

Example:

source_type

enum<string>

read-onlyoptional

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

Allowed values:

customorderclone

Default:

custom

status

enum<string>

optional

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:

Move Collection to Backlog

Move Collection to Board

Allowed values:

plannednot_plannedignored

Example:

not_planned

progress

enum<string>

read-onlyoptional

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

Allowed values:

openpartialdone

Example:

open

warnings

array[string]

read-onlyoptional

Example:

[]

custom_fields

array[object (CustomField) {13}]

required

string <uuid>

read-onlyoptional

Unique identifier

name

string

optional

Name of the field

Example:

Weight

type

enum<string>

optional

Allowed values:

textnumberdatecheckboxemaillinkphonelistselectaddressdrawingtextareausers

Default:

text

Example:

number

scope

enum<string>

optional

Allowed values:

collectioncard

priority

integer

optional

Priority of the custom field in which the fields are ordered in the frontend

Example:

value

optional

drawing_id

string <uuid>

optional

components

object (CustomFieldOptionsAddress)

optional

list

array [object {3}]

optional

selected

object

optional

options

optional

Extra settings for number, select or list types

created_at

string <date-time>

read-onlyoptional

Date and time of creation

Example:

2024-04-11T10:22:15Z

updated_at

string <date-time>

read-onlyoptional

Date and time of last update

Example:

2024-04-11T10:22:15Z

board_id

string <uuid>

required

Unique identifier of the Board

cover_image_url

string <uri> | null

optional

cover_image_signature

string | null

read-onlyoptional

cover_image_bytes

integer

read-onlyoptional

>= 0

cover_color_hex

string | null

optional

Examples:

#FFF#8d46e0

Match pattern:

^#([A-Fa-f0-9]{3}){1,2}$

external_ref

string | null

read-onlyoptional

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

Example:

fb1033a2ed70

created_at

string <date-time>

read-onlyoptional

Date and time of creation

Example:

2024-04-11T10:22:15Z

updated_at

string <date-time>

read-onlyoptional

Date and time of last update

Example:

2024-04-11T10:22:15Z

Example

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "Order 10199",
  "description": "3x Chair Lissabon",
  "start": "2020-01-02",
  "end": "2020-08-13",
  "due_date": "2020-01-02",
  "meta": {
    "bar": "foo",
    "baz": "quux"
  },
  "position": 13,
  "source_type": "custom",
  "status": "planned",
  "progress": "open",
  "warnings": [],
  "custom_fields": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "Weight",
      "type": "text",
      "scope": "collection",
      "priority": 0,
      "value": "string",
      "drawing_id": "19ba6f6f-3365-4d74-bdc5-b3df4072c0ab",
      "components": {
        "latitude": 52.3156048,
        "longitude": 6.496432,
        "country": "Netherlands",
        "city": "Rijssen",
        "postal_code": "7462TB",
        "street1": "Hogepad 83",
        "street2": "Second floor"
      },
      "list": [
        {
          "name": "string",
          "value": "string",
          "color": "transparent"
        }
      ],
      "selected": {
        "name": "string",
        "value": "string",
        "color": ""
      },
      "options": {
        "unit": "kg",
        "align": "left",
        "decimals": 2
      },
      "created_at": "2024-04-11T10:22:15Z",
      "updated_at": "2024-04-11T10:22:15Z"
    }
  ],
  "board_id": "75e8c400-2dbc-43a3-9af4-ff9e6c099385",
  "cover_image_url": "http://example.com",
  "cover_image_signature": "string",
  "cover_image_bytes": 0,
  "cover_color_hex": "#FFF",
  "external_ref": "fb1033a2ed70",
  "created_at": "2024-04-11T10:22:15Z",
  "updated_at": "2024-04-11T10:22:15Z"
}

🟠422Unprocessable Content

🟠404Not Found

🟠401Not Logged In