api:forms

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
Show response

{
  "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"
              },
              {
                "id": 6,
                "type": "money",
                "name": "Amount"
              }
            ]
          }
        }
      ]
    }
  ]
}

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    
Show response

{
  "tasks": [{
    "id": 11610,
    "create_date": "2017-08-20T12:31:14Z",
    "last_modified_date": "2017-08-23T10:20:11Z",
    "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"
              },
              {
                "id": 6,
                "type": "money",
                "name": "Amount",
                "value": 10000
              }
            ]
          },
          {
            "row_id": 1,
            "cells": [
              {
                "id": 5,
                "type": "date",
                "name": "Date",
                "value": "2017-08-27"
              },
              {
                "id": 6,
                "type": "date",
                "name": "Amount"
                "value": 306.25
              }
            ]
          }
        ]
      }
    ]
  }]
}

Parameters

steps Step number. You can specify multiple steps separated by a comma.
include_archived Specify "y" if you want to include archived tasks in the response.
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.

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

Was this article helpful?

Yes, thanks! No, I have a question