Form fields format

Cloud Pyrus

Cloudless Pyrus

The form field is described by the JSON object, which contains a unique field number, field name, type, current value, and additional information about the filling rules.

{
  "id": 15,
  "name": "Summary",
  "type": "text",
  "value": "Printer does not print",
  "code": "SummaryCode",
  "info": {
    "immutable_step": 1,
    "required_step": 1
  }
}

Depending on the method being called, only some properties are passed and returned:

Request	id	name	code	type	value	info	parent_id	row_id
GET /forms	✔	✔	✔	✔		✔	✔
GET /forms/{form-id}	✔	✔	✔	✔		✔
GET /forms/{form-id}/register	✔	✔	✔	✔	✔		✔	✔
GET /tasks/{task-id}	✔	✔	✔	✔	✔		✔	✔
POST /tasks/{task-id}/comments	✔*				✔
POST /tasks	✔*				✔

* You must specify at least one of these parameters

Field Types and Examples

There are two types of fields: primitive and composite. Primitive types take the value of standard data types (string, number, date) as a field value. Composite types take a JSON object.

Primitive types

Type	Description	Example
text		"value": "IT Conference"
money		"value": 1365.27
number		"value": 157.2134
date	Date format: YYYY-MM-DD	"value": "2017-03-16"
time	Time format: HH:mm	"value": "17:26"
checkmark	Possible values: checked unchecked	"value": "checked"
due_date	Date format: YYYY-MM-DD "duration": duration in minutes, optional	"value": "2017-03-16" "duration": "140"
due_date_time	Date format: YYYY-MM-DDThh:mm:ssZ "duration": duration in minutes, optional	"value": "2017-03-16T14:53:23Z" "duration": "140"
email		"value": "consumer@mycompany.com"
phone		"value": "+7 800 555 3565"
flag	Possible values: none checked unchecked	"value": "unchecked"
step	read only	"value": 1
status	read only Possible values: open closed	"value": "open"
creation_date	read only. Date format: YYYY-MM-DDThh:mm:ssZ. Returned in UTC	"value": "2017-03-18T14:53:23Z"
note	read only	"value": "This is a tooltip"

To write to the primitive type, you must pass the id or name and a new field value.

Composite types

catalog Read:

Single choice catalog:

"value": {
    "item_id": 80797460,
    "item_ids": [
        80797460
    ],
    "headers": [
        "Vendor Name",
        "Vendor Code"
    ],
    "values": [
        "GE",
        "123"
    ],
    "rows": [
        [
            "GE",
            "123"
        ]
    ]
}

Multiple choice catalog:

"value": {
    "item_ids": [
        80797460,
        80797461
    ],
    "headers": [
        "Vendor Name",
        "Vendor Code"
    ],
    "rows": [
        [
            "GE",
            "123"
        ],
        [
            "VN",
            "321"
        ]
    ]
}

Write:

Single choice catalog: you can pass either catalog item identifier,

"value": {
  "item_id": 23
}

or element value:

"value": {
  "item_name": "GE"
}

Multiple choice catalog:

"value": {
    "item_ids": [
        80797460,
        80797461
    ]
}

or:

"value": {
    "item_names": [
        "GE",
        "VN"
    ]
}

file Read:

"value": [{
  "id": 17563,
  "name": "S15294-16.pdf",
  "size": 541512,
  "md5": "202cb962ac59075b964b07152d234b70",
  "url": "https://api.pyrus.com/files/17563",
  "version": 2,
  "root_id": 17562
}]

Write:

See the format of the attachments parameter values in the task creation method or the comment addition method.

person Read:

"value": {
  "id": 1730,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "Jane.Doe@gmail.com",
  "type": "user"
}

Write:

You can pass either the person's identifier:

"value": {
  "id": 1730,
}

Or their email:

"value": {
  "email": "Jane.Doe@gmail.com",
}

author (read only) Read:

"value": {
  "id": 1730,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "Jane.Doe@gmail.com",
  "type": "user"
}

table Read:

"value": [
    {
    "row_id": 0,
    "position": 1,
    "cells": [
      {
        "id": 6,
        "type": "date",
        "name": "Date",
        "value": "2017-08-26",
        "parent_id": 5,
        "row_id": 0,
      },
      {
        "id": 9,
        "type": "money",
        "name": "Amount",
        "value": 10000,
        "parent_id": 5,
        "row_id": 0,
      }
    ]
  },
  {
    "row_id": 1,
    "position": 1,
    "cells": [
    {
      "id": "6",
      "type": "date",
      "name": "Date",
      "value": "2017-08-27",
      "parent_id": 5,
      "row_id": 1,
    },
    {
      "id": 9,
      "type": "money",
      "name": "Amount",
      "value": 306.25,
      "parent_id": 5,
      "row_id": 1,
    }
  ]}
]

Write:

"value": [{
    "row_id": 0,
    "position": 1,
    "delete": true
  },
  {
  "row_id": 1,
  "cells": [
    {
      "id": 9,
      "value": 351.25
    },
    {
      "id": 6,
      "value": "2017-08-21"
    }
  ]
}]

Note: When displaying the table, the order of its rows is determined by the position parameter. If this parameter is not specified, the order is formed based on the row_id row identifiers, from smallest to largest. This enables adding a new row in the middle of the table or changing the order of its rows.

multiple_choice Read:

"value": {
  "choice_ids": [5],
  "choice_names": ["Yes"]
  "fields": [
    {
      "id": 6,
      "type": "text",
      "name": "Comment",
      "value": "Additional information about choice",
      "parent_id": 4
    },
    {
      "id": 9,
      "type": "number",
      "name": "Quantity",
      "value": 15,
      "parent_id": 4
    }
  ]
}

Write:

"value": {
    "choice_ids": [5]
    "fields": [
      {
        "id": 9,
        "value": 1
      }
    ]
  }

title Read:

"value": {
  "checkmark": "checked",
  "fields": [
    {
      "id": 3,
      "type": "date",
      "name": "Date",
      "value": "2017-08-19",
      "parent_id": 2
    },
    {
      "id": 4,
      "type": "text",
      "name": "Description",
      "value": "My issue",
      "parent_id": 2
    }
  ]
}

Write:

"value": {
  "fields": [
    {
      "id": 4,
      "value": "It is not an issue"
    }
  ]
}

form_link Read:

"value": {
  "task_ids": [1573],
  "subject": "Expense report"
}

Write:

"value": {
  "task_ids" : [1753]
}

project (deprecated, read only) Read:

"value": {
  "projects": [
    {
      "id": 1,
      "name": "Root Project"
    },
    {
      "id": 3,
      "name": "Child Project",
      "parent": {
        "id": 2,
        "name": "Another root project"
      }
    }
  ]
}

Additional field information

The info object can contain two keys for every field type:

required_step — indicates the step number where the field becomes required for filling.
immutable_step — indicates the step number from which the user can't change the field value. Step numbering begins with 1.

Also, the info object can contain the field code (code) if it is not empty, the required flag (required), and the flag indicating whether the field is included in the form task title (is_form_title).

In addition to the listed keys, the info object may contain one of the additional keys, depending on the field type:

Type	Key	Example
multiple_choice	options	"options": [ { "choice_id": 0, "choice_value": "Not Set" }, { "choice_id": 1, "choice_value": "Yes", "fields": [{ "id": 4, "type": "text", "name": "Reason", "parent_id": 3, }] }, { "choice_id": 2, "choice_value": "No", }, { "choice_id": 3, "choice_value": "MayBe", "deleted": true } ]
catalog	catalog_id	"catalog_id": 165
table	columns	"columns": [ { "id": 9, "type": "money", "name": "Amount", "parent_id": 5, }, { "id": 6, "type": "date", "name": "Date", "parent_id": 5, } ]
title	fields	"fields": [ { "id": 9, "type": "money", "name": "Amount", "parent_id": 5, }, { "id": 6, "type": "date", "name": "Date", "parent_id": 5, } ]
form_link	form_id	"form_id": 1453
number	decimal_places	"decimal_places": 5
catalog	multiple_choice	"multiple_choice": true

Form fields format

Field Types and Examples

Primitive types

Composite types

Additional field information

Was this article helpful?