Help Center

Forms

Forms are a set of fields and routing rules that describe a business process.

A typical example here is reimbursing an employee for travel expenses.

Form fields are a data set that each business process participant works with.

The travel reimbursement business process may include form fields for an employee's last name, the date of the trip, the total reimbursement request, and receipts.

The workflow Is a set of rules that describe how a task moves throughout its business process. Workflows are usually divided into steps. Each step can be given a name, and you can configure rules for automatically adding participants at relevant steps.

For example, the “Travel expense reimbursement” workflow can be divided into the following steps:

"Fill". At this step, the author of the task fills out all the required fields and attaches the supporting documents.

"Approval". At this step, you can add different users to the task, depending on the amount requested.

"Accounting". At this step, the accountant reimburses the employee for the expenses.

You can find additional information about forms in the help section.

Methods

GET /forms

This method returns a description of all the forms in which the current user is a manager or a member.

GET https://api.pyrus.com/v4/forms

Response body

{
  "forms": [
    {
      "id": 36120,
      "name": "Payments",
      "steps": {
        "1": "Manager",
        "2": "Accounting",
        "4": "CEO"
      },
      "fields": [
        {
          "id": 1,
          "type": "text",
          "name": "Purpose",
          "info": {
            "required_step": 1,
            "immutable_step": 1
          }
        },
        {
          "id": 2,
          "type": "money",
          "name": "Amount",
        },
        {
          "id": 3,
          "type": "catalog",
          "name": "Payment type",
          "info": {
            "catalog_id": 277
          }
        },
        {
          "id": 4,
          "type": "table",
          "name": "Payment Schedule",
          "info": {
            "columns": [
              {
                "id": 5,
                "type": "date",
                "name": "Date",
                "parent_id": 4
              },
              {
                "id": 6,
                "type": "money",
                "name": "Amount",
                "parent_id": 4
              }
            ]
          }
        }
      ],
      "deleted_or_closed": false,
      "print_forms": [
        {
          "print_form_id": 2633,
          "print_form_name": "templateA.docx"
        },
        {
          "print_form_id": 2645,
          "print_form_name": "templateB.xlsx"
        }
      ],
      "folder": [folder1]
    }
  ]
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/forms/' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

You can find a full list of field types in the Form fields format section.

GET /forms/{form-id}

This method returns a description of form with inputted id.

GET https://api.pyrus.com/v4/forms/36120

Response body

{
  "id": 36120,
  "name": "Payments",
  "steps": {
	"1": "Manager",
	"2": "Accounting",
	"4": "CEO"
  },
  "fields": [
	{
	  "id": 1,
	  "type": "text",
	  "name": "Purpose",
	  "info": {
		"required_step": 1,
		"immutable_step": 1
	  }
	},
	{
	  "id": 2,
	  "type": "money",
	  "name": "Amount",
	},
	{
	  "id": 3,
	  "type": "catalog",
	  "name": "Payment type",
	  "info": {
		"catalog_id": 277
	  }
	},
	{
	  "id": 4,
	  "type": "table",
	  "name": "Payment Schedule",
	  "info": {
		"columns": [
		  {
			"id": 5,
			"type": "date",
			"name": "Date",
			"parent_id": 4
		  },
		  {
			"id": 6,
			"type": "money",
			"name": "Amount",
			"parent_id": 4
		  }
		]
	  }
	}
  ],
  "deleted_or_closed": false,
  "print_forms": [
	{
	  "print_form_id": 2633,
	  "print_form_name": "templateA.docx"
	},
	{
	  "print_form_id": 2645,
	  "print_form_name": "templateB.xlsx"
	}
  ],
  "folder": [folder1]
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/forms/36120' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

You can find a full list of field types in the Form fields format section.

GET /forms/{form-id}/register

This method returns the list of tasks that were created based on the specified form. The response only contains general information about the task, like the list of filled form fields and its workflow. You can use the GET /tasks/{task-id} method to get all task comments.

GET https://api.pyrus.com/v4/forms/1423/register
    ?fld2=gt10000,lt15000
    &fld1=IT%20conference%20in%20Amsterdam
    &fld3=277
    &include_archived=y

Response body

{
  "tasks": [{
    "id": 11610,
    "create_date": "2017-08-20T12:31:14Z",
    "last_modified_date": "2017-08-23T10:20:11Z",
    "current_step": 1,
    "fields": [
      {
        "id": 1,
        "type": "text",
        "name": "Purpose",
        "value": "IT conference in Amsterdam"
      },
      {
        "id": 2,
        "type": "money",
        "name": "Amount",
        "value": 10306.25
      },
      {
        "id": 3,
        "type": "catalog",
        "name": "Payment type",
        "value": {
          "item_id": 845,
          "headers": [
            "Payment types"
          ],
          "values": [
            "IT Conference"
          ]
        }
      },
      {
        "id": 4,
        "type": "table",
        "name": "Payment Schedule",
        "value": [
          {
            "row_id": 0,
            "cells": [
              {
                "id": 5,
                "type": "date",
                "name": "Date",
                "value": "2017-08-26",
                "parent_id": 4,
                "row_id": 0
              },
              {
                "id": 6,
                "type": "money",
                "name": "Amount",
                "value": 10000,
                "parent_id": 4,
                "row_id": 0
              }
            ]
          },
          {
            "row_id": 1,
            "cells": [
              {
                "id": 5,
                "type": "date",
                "name": "Date",
                "value": "2017-08-27",
                "parent_id": 4,
                "row_id": 1
              },
              {
                "id": 6,
                "type": "date",
                "name": "Amount",
                "value": 306.25,
                "parent_id": 4,
                "row_id": 1
              }
            ]
          }
        ]
      }
    ]
  }]
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/forms/327874/register?fld2=gt10000,lt15000&fld1=IT%20conference%20in%20Amsterdam&fld3=277&include_archived=y' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

If filtering parameters' size exceeds the maximum URL length, you can call this method via the HTTP POST request. Parameters are specified in the request body in JSON format.

{
    "fld2": "gt10000,lt15000",
    "fld1": "IT conference in Amsterdam",
    "fld3": "eq277",
    "include_archived": "y"
}

Parameters

stepsStep number. You can specify multiple steps separated by a comma.
task_idsThe task numbers of the tasks the form register will be limited to.
include_archivedSpecify "y" if you want to include archived tasks in the response.
field_idsField ids which values will be returned in the response. All fields are returned by default. You can specify multiple field ids separated by a comma. This parameter also affects the order of the returned fields in case of the csv format. If the parameter is not passed, all fields are returned. If the parameter is passed but does not contain ids, then form fields will be missing from the reply.

fld{field_id}

Filter task by field:

  • Exact match: fld1=Payment
  • Is in list: fld14=15,20
  • Greater than: fld3=gt15
  • Less than: fld5=lt2017-01-01
  • Between: fld3=gt15.5,lt21

lt and gt operators are applicable only to the following field types: date, money, number, due_date, creation_date.

The "Is in list" operator is also applicable to the fields multiple_choice, catalog, person, author, form_link.

Record identifier is used as a filter value for composite types.

You can find additional information about field types in the Form fields format section.

Filtering is not supported for the following field types: file, time, table, title, project, note.

formatSpecify "csv", if you want to get the result in csv format. The default response format is json.
delimiterField separator in the csv file. By default — ",".
encodingResponse encoding. By default — "utf-8".
simple_formatSpecify "y", if you want to get the csv file in the simplified format.All line breaks will be replaced with spaces.
modified_beforeTasks modified before specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ
modified_afterTasks modified after specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ
created_beforeTasks created before specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ
created_afterTasks created after specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ
closed_beforeTasks closed before specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ
closed_afterTasks closed after specified date in UTC (inclusive).Date format: YYYY-MM-DDThh:mm:ssZ
item_countMax. number of tasks in request.Value must be more than 0, and less than or equal to 20000.

Form permissions

You can edit access rights to a form. To request the methods for this, email Pyrus tech support at support@pyrus.com. Read about form permissions in more detail here.

Access levels:

  • "administrator" — form administrator;
  • "manager" — form manager (without conditions);
  • "member" — form participant;
  • "none" — no access (only used when settings are changed to deny access to a user).

GET /forms/{form-id}/permissions

This method enables receiving a list of user permissions for the form.

GET https://api.pyrus.com/v4/forms/36120/permissions

Response body

{
    "permissions": {
        "1733": "manager",
        "1731": "administrator"
    }
}

curl

curl -X GET \
  'https://api.pyrus.com/v4/forms/327874/permissions' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

POST /forms/{form_id}/permissions

To change a user’s access rights, indicate the new rights for that user in the body of the reply. The format of the body of the reply is the same as for receiving the list of form permissions.

Limitations:

  • the administrator’s rights cannot be edited, and new administrators cannot be added to the form;
  • form managers cannot be added with conditions.
POST https://api.pyrus.com/v4/forms/36120/permissions

Request body

{
    "permissions": {
        "1733": "member"
    }
}

Response body

{
    "permissions": {
        "1733": "member",
        "1731": "administrator"
    }
}

curl

curl -X POST \
  https://api.pyrus.com/v4/forms/36120/permissions \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "permissions": {
        "1733": "member"
    }
}'

Was this article helpful?