api:fields

Form fields format

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",
  "info": {
    "immutable_step": 1,
    "required_step": 1
  }
}

Depending on the method being called, only some properties are passed and returned:
Method id name type value info
GET /forms
GET /forms/{form-id}/register
GET /tasks/{task-id}
POST /tasks/{task-id}/comments *
POST /tasks *

* At least one of these parameters must be specified.

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
"value": "2017-03-16"
due_date_time Date format:
YYYY-MM-DDThh:mm:ssZ
"value": "2017-03-16T14:53:23Z"
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-DD
Returned by UTC
"value": "2017-03-18"
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:

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

Write :

You can pass either catalog item identifier:
"value": {
  "item_id": 23
}
or element value:
"value": {
  "item_name": "GE"
}

file
Read:

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

Write:

"value": [
  "66fcc656-9182-4d4a-9d1f-ece882cd12cd",
  "3b5ff13b-e561-4b56-9db2-bea4f8677429"
]
You can upload files and get their identifiers using the files/upload method.

person
Read:

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

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

table
Read:

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

Write:

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

multiple_choice
Read:

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

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"
    },
    {
      "id": "4",
      "type": "text",
      "name": "Description",
      "value": "My issue"
    }
  ]
}

Write:

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

form_link
Чтение:

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

Запись:

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

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"
    }
  },
  {
    "choice_id": 2,
    "choice_value": "No",
  }
]
catalog catalog_id
"catalog_id": 165
table columns
"columns": [
  {
    "id": 9,
    "type": "money",
    "name": "Amount"
  },
  {
    "id": 6,
    "type": "date",
    "name": "Date"
  }
]
title fields
"fields": [
  {
    "id": 9,
    "type": "money",
    "name": "Amount"
  },
  {
    "id": 6,
    "type": "date",
    "name": "Date"
  }
]
form_link form_id
"form_id": 1453

Was this article helpful?

Yes, thanks! No, I have a question