Overview

The Pyrus API offers applications the ability to access the tasks and projects of a particular user. The objective of this documentation is to provide developers a guide toward the implementation of the Pyrus API with third-party services in a secure manner. To get started, you must first do the following:

1. Register the application at Pyrus and get an Client ID and a Secret Key. Those ID's are needed to get AccessToken(access_token), which is required for secure invocation of Pyrus API methods.

2. Users of your application must be Pyrus registered users.

Once you have registered, you can access any methods available on our API.

Authorization

Pyrus API uses OAuth 2.0 protocol for authentication and authorization. Requests should be made over a secure connection SSL(https://).

Every method requested requires:

Client ID which identifies your application.
AccessToken(access_token), used to verify and authenticate the request.

Pyrus supports two types of authorization:

Authorization for web application. This type is prefered. Use it in case your application has GUI and it can show user special form to enter login and password.
Authorization for background process. This should be used if your application has no GUI.

As a result of authorization process, your application will get AccessToken(access_token), which should be used for each invocation of Pyrus API's methods. AccessToken(access_token) is limited by the time and could be revoked by an user. In this case you should authorize your application again.

Application registration

After application being registered you'll receive Client ID and Client Secret. Those ID's are needed to get AccessToken(access_token), which is required for secure invocation of Pyrus API methods.

Please log in to edit OAuth registration.

Get Task

Retrieving a task is implemented with the GetTask method. GetTask accepts Task Identifier, and returns an object containingTaskWithNotes structure.

URL https://pyrus.com/restapi/v3/task/{taskid} is used as REST endpoint with the http method GET. {taskid} -Task Identifier.

Example

GET https://pyrus.com/restapi/v3/task/1024
Header Authorization: Bearer gAAAAA15vmSeoj*******

Response Body

{
    "TaskWithNotes": {
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1713916800000)/",
        "Author": {
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        },
        "Approvals": [[{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        },
        {
            "Person": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }
        }],
        [{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        }]],
        "Notes": [{
            "CreateDate": "/Date(1713916800000)/",
            "Author": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            "ReassignedTo": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            },
            "AddedProjects": [{
                "Id": 1,"Name": "Root project"
            },
            {
                "Id": 3,
                "Name": "ChildProject",
                "Parent": {
                    "Id": 2,
                    "Name": "Another root project"
                }
            }],
            "DueDateChanged": "/Date(1713916800000)/",
            "ApprovalsAdded": [[{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }],
            [{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }]],
            "Id": 0
        }]
    }
}

Aside from authorization and format errors, the method can return the following custom error codes:

403 Access denied:

BehavioralTaskAccessViolation: No access to task. Specified user has no rights to change the task that way;

Structure TaskWithNotes describes task with comments and has the following properties:

Id: task identifier;
Text: task text;
Responsible: person, who is responsible for the task, an instance of the structure Person;
DueDate: task due date, this parameter represents date in UTC format without hours, minutes and seconds. If the task does not have due date, the parameter is skipped;
Asap: asap flag, if it equals to false, the parameter is not specified;
Projects: array of task projects;
CloseDate: close date, if the task is opened, this parameter is skipped;
CreateDate: create date;
ModifiedDate: modified date;
ParentTaskId: parent Task Id;
Author: task author, an instance of the structure Person;
Approvals: task approvals, represents array of approval steps, which are arrays of PersonApproval structure. Some approval steps could be skipped, therefore array of PersonApproval will be equal to null;
Form: form values array, can be empty;
Notes: array of task comments, each element of the array represents TaskNote structure. Each task has at least one comment - initial;
IsAnyRejected: flag indicating that one or more approval steps were rejected;
FormTemplateId: form template identifier;

Structure TaskNote describes task comment and has the following properties:

CreateDate: comment creation date;
Author: author of the comment, an instance of the structure Person;
Text: comment text, can be empty, therefore skipped;
ReassignedTo: person, who the task was reassigned, if there were no reassigning, the parameter stays skipped, an instance of the structure Person;
ActivityAction: reopening or closing flag, the default value is skipped, an instance of the enumeration with the following fixed values: None - default value, keep task activity unchanged, Complete, MarkAsDuplicate, MarkAsIrrelevant, Reopen;
ApprovalChoice: approval of the author of comment, this parameted can be skipped, an instance of the enumeration with the following fixed values: Waiting - waiting for approval, this is the default value, Approved, Rejected, Revoked, Acknowledged;
AddedProjects: array of added projects;
RemovedProjects: array of removing projects;
DueDateChanged: due date was changed;
DueDateRemoved: if the due date was cleared, this parameter equals to true. DueDateChange is skipped also in this case;
ApprovalsAdded: adding approvals, represents array of approval steps, each of step is array of persons;
ApprovalsRemoved: removed approvals;
ApprovalsRerequested: rerequested approvals;
Attachments: attached files;
Id: id;
Form: form values array, can be empty;
TaskId: ;
UserId: ;
EditNoteId: identifier of the edited comment;
DeleteNoteId: identifier of the deleted comment;
RemovedAttachmentIds: removed attachment IDs;
SpentMinutes: spent time in minutes;

Structure PersonApproval describes approval state of fixed person and has the following properties:

Choice: approval choice, the default value could be skipped, an instance of the enumeration with the following fixed values: Waiting - waiting for approval, this is the default value, Approved, Rejected, Revoked, Acknowledged;

Structure Attachment describes the file attached to the task note and has the following properties:

Id: Id;
Name: file name;
Size: file size in bytes;
DownloadUrl: URL to download contents;
ExistingId: Root file Id;
MD5Hash: MD5 hash;

If the task is a form, the 'TaskWithNotes' structure contains 'Form' field, which is an array of objects each having a type derived from FormValue.

Structure FormValue describes the value of a single form field and has the following properties:

Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormField contains meta-information concerning a form field and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

The actual value of each form field is returned as an object having a type derived from FormValue. Below all possible derived types are described.

Structure FormFieldActivityStatus.ValueType describes the status of this task (closed/open) and has the following properties:

ActivityStatus: status of this task, an instance of the enumeration with the following fixed values: Opened - open, Closed - closed;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldApprovalDate.ValueType represents the date when an approval status was set for this task and has the following properties:

ApprovalDate: date when an approval status was set for this task;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldApprovalPerson.ValueType represents the person who set an approval status for this task and has the following properties:

ApprovalPerson: the person who set an approval status for this task, an instance of the structure Person;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldApprovalStep.ValueType represents the no. of approval step this task is currently on and has the following properties:

ApprovalStep: no. of approval step this task is currently on;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldAssignee.ValueType represents the person responsible for this task and has the following properties:

Assignee: the person responsible for this task, an instance of the structure Person;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldAuthor.ValueType represents the author of this task and has the following properties:

Author: the author of this task, an instance of the structure Person;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldCheckmark.ValueType describes a checkbox field value and has the following properties:

Checkmark: checkbox field value, an instance of the enumeration with the following fixed values: Checked, Unchecked;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldCreationDate.ValueType represents the date when this form was created and has the following properties:

CreationDate: the date when this form was created;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldDate.ValueType represents a date field value and has the following properties:

Date: date field value;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldDecimal.ValueType represents a money field value and has the following properties:

Decimal: money field value;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldDueDate.ValueType represents a deadline date for this task and has the following properties:

DueDate: deadline date for this task;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldFiles.ValueType represents a set of one or more files and has the following properties:

Files: a set of one or more files;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldFlag.ValueType describes a yes/no field value and has the following properties:

Flag: yes/no field value, an instance of the enumeration with the following fixed values: None, Checked, Unchecked;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldNote.ValueType represents an empty object returned for readonly text fields and has the following properties:

Tooltip: note field value;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldNumber.ValueType represents a number field value and has the following properties:

Number: number field value;
DecimalNumber: number field value in decimal format;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldPerson.ValueType represents a person and has the following properties:

Person: a person, an instance of the structure Person;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldPhone.ValueType represents a phone number and has the following properties:

Phone: phone number (an object with two fields: 'Prefix' and 'Number'), an instance of the structure Phone;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldProject.ValueType represents a project and has the following properties:

Project: a project, an instance of the structure Project;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldText.ValueType represents a text field value and has the following properties:

Text: text field value;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldTime.ValueType represents a time field value and has the following properties:

Time: time field value (an object with two integer fields: 'UtcHour' и 'UtcMinute'), an instance of the structure Time;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldTitle.ValueType represents an empty object returned for a form section title and has the following properties:

Rows: current table rows info;
Checkmark: current optional section info;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldCatalog.ValueType represents a catalog item field value and has the following properties:

CatalogItemId: catalog item ID;
CatalogItemValues: catalog item field value;
CatalogHeaders: catalog item headers;
Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Structure FormFieldUnknown.ValueType and has the following properties:

Field: meta-information on this form field, an instance of the structure FormField;
RowId: row index, if field is a part of table;

Please, be aware that some types of field values may not be fully supported via API.

Methods

After successful authentication, the following methods are available via a secured protocol (HTTPS):

Get Task
Get Task List
Get All Tasks
Create Task
Create Comment
Get Profile
Get Contacts

All methods are only available using https channel and placed on https://pyrus.com.

The API supports REST.

Content-Type Header

Pyrus API uses JSON as a data format so Content-Type of each request must be specified with "application/json".

Authorization Header

Each request must contain an authorization header based on OAuth v2 specifications.

Compression

All requests are compressed using standard gzip and deflation algorithms. It is highly recommended to use this option when transmitting large amounts of data.

Data Formats

The API uses the following standard data types:

String
Integer
Bit Flag
DateTime
Array
Enumeration
Structures

DateType is serialized in JSON format as a string: "/Date(1198908717056)/", which is a UNIX TIMESTAMP. For XML serialization, the ISO 8601 standard is used. XML date value is always in UTC. For example: "2012-04-10T09:08:07Z". Milliseconds in dates are ignored.

Enumerations are serialized as string types, whose values lie within a fixed range. One of the fixed values can be the default, and therefore skipped from the request or response body.

Below is description of commonly used structures.

Structure Person describes person and has the following properties:

Id: person identifier;
FirstName: person first name, can be empty;
LastName: person last name;
Email: person email;
CanSendNotification: can send message;
PersonsInRole: List of Persons in role;

Structure Project describes project and has the following properties:

Id: project identifier;
Name: project name;
Parent: parent project, if the current project is root then it`s parent is empty;

Error Handling

If an error occurs, the API will return a corresponding HTTP Status Code. In addition, the server will provide further information inside string ﬁelds such Code and Description. For REST requests, the server returns a JSON Error structure with the described fields.

Below is an example of an error response.

REST

Response Headers
Content-Encoding:	gzip
Content-Type:	application/json; charset=utf-8
Response Body
{ "ApiException" : { "Code" : "BadFormat", "Message" : "Some error text" } }

String field Code represents error code. Codes are grouped by these means: BadFormat - format errors, Authorization - authorization errors, Behavioral - access errors. Each method can return their own errors which are described in corresponding method sections. Below is the list of common errors:

400 Invalid request:

BadFormat: Invalid argument of invoked method. Make sure, that all values, used as arguments for method invocation, have valid type;
BadFormatInteger: Invalid value in parameter of integer type. Make sure you are sending integer value as a method parameter;
BadFormatDate: Invalid value in date- parameter. Make sure, that the value you put as date- parameter (e.g. DueDate in CreateTask method), has proper format;

401 No authorization:

AuthorizationError: Authorization error. Make sure that you've performed authorization process;
AuthorizationErrorInvalidToken: Invalid authorization token. Receive new token by performing appropriate procedure for web application or background process;
AuthorizationErrorRevokedToken: Authorization token has been revoked. Receive new token by performing appropriate procedure for web application or background process;
AuthorizationErrorExpiredToken: Authorization token has been expired. Receive new token by performing appropriate procedure for web application or background process;
AuthorizationErrorTokenNotSpecified: Authorization token not specified. In order to invoke Pyrus API's methods, you need to specify AccessToken(access_token) received during authorization;

403 Access denied:

UnspecifiedAccessDenied: Access is denied. Сheck if user, that is making an edition of the task, has rights to do it;

Get Task List

There are two ways to get a task list: Get Inbox Task List and Search Tasks.

Get Inbox Task List

You can retrieve tasks from an Inbox using the GetInbox method. GetInbox accepts the MaximumItemsCount(default: 50) parameter, the maximum number of tasks to return. The GetInbox method returns the TaskList structure.

URL https://pyrus.com/restapi/inbox is used as REST endpoint with the http method GET.

Example

GET https://pyrus.com/restapi/inbox/3
Header Authorization: Bearer gAAAAA15vmSeoj*******

Response Body

{
    "Tasks": [{
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1714006597076)/",
        "ModifiedDate": "/Date(1714006597076)/"
    },
    {
        "Id": 1025,
        "Text": "Another task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1714006597076)/",
        "ModifiedDate": "/Date(1714006597076)/"
    },
    {
        "Id": 1026,
        "Text": "Closed task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CloseDate": "/Date(1714006597000)/",
        "CreateDate": "/Date(1714006597076)/",
        "ModifiedDate": "/Date(1714006597076)/"
    }],
    "HasMoreTasks": true
}

Search Tasks

Searching tasks is implemented through the SearchTasks method. SearchTasks accepts the SearchTasksParams structure, which contains search parameters, and returns a TaskList structure.

URL https://pyrus.com/restapi/searchtasks is used as REST endpoint with the http method POST.

Example

POST https://pyrus.com/restapi/searchtasks
Header Authorization: Bearer gAAAAA15vmSeoj*******

Request Body

{
    "AuthorId": 300,
    "MaximumItemsCount": 3
}

Response Body

{
    "Tasks": [{
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1714006597076)/",
        "ModifiedDate": "/Date(1714006597076)/"
    },
    {
        "Id": 1025,
        "Text": "Another task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1714006597076)/",
        "ModifiedDate": "/Date(1714006597076)/"
    },
    {
        "Id": 1026,
        "Text": "Closed task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CloseDate": "/Date(1714006597000)/",
        "CreateDate": "/Date(1714006597076)/",
        "ModifiedDate": "/Date(1714006597076)/"
    }],
    "HasMoreTasks": true
}

Structure SearchTasksParams describes search tasks properties and has the following properties:

ProjectIds: project filter, represents an array of project identifiers. If more than one project is specified, the task must be added to each of them;
IncludeClosedTasks: include closed tasks in search, by default equals to false;
ParticipantIds: participants filter, represents array of person identifiers;
AuthorId: author identifier, skipped by default;
ResponsibleId: current responsible identifier, skipped by default;
MaximumItemsCount: maximum count of tasks returned, 50 by default. increase this parameter if you need more tasks. Max value is 10000.;
IncludeText: including substring;
ExcludeText: excluding substring, if the parameter is specified, you should specify IncludeText parameter also;
ActiveFrom: search period start date;
ActiveTo: search period end date;
CreateFrom: Create task date filter. search period start date;
CreateTo: Create task date filter. search period end date;

Structure TaskList describes task list and has the following properties:

Tasks: task array, each element of the array represents Task structure;
HasMoreTasks: this flag is true when server returned N tasks, use MaximumItemsCount parameter to get more tasks. When server returned all tasks this flag is skipped;

Structure Task describes task and has the following properties:

Id: task identifier;
Text: task text;
Responsible: person, who is responsible for the task, an instance of the structure Person;
DueDate: task due date, this parameter represents date in UTC format without hours, minutes and seconds. If the task does not have due date, the parameter is skipped;
Asap: asap flag, if it equals to false, the parameter is not specified;
Projects: array of task projects;
CloseDate: close date, if the task is opened, this parameter is skipped;
CreateDate: create date;
ModifiedDate: modified date;
ParentTaskId: parent Task Id;

Get All Tasks

Searching all tasks the user has access to.

Get All Tasks

You can retrieve all tasks from an Inbox using the GetAllTasks method. GetAllTasks accepts the MaximumItemsCount(default: 50) parameter, the maximum number of tasks to return. The GetAllTasks method returns the TaskList structure.

URL https://pyrus.com/restapi/alltasks is used as REST endpoint with the http method GET.

Example

GET https://pyrus.com/restapi/alltasks/3
Header Authorization: Bearer gAAAAA15vmSeoj*******

Response Body

{
    "Tasks": [{
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1714006597078)/",
        "ModifiedDate": "/Date(1714006597078)/"
    },
    {
        "Id": 1025,
        "Text": "Another task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1714006597078)/",
        "ModifiedDate": "/Date(1714006597078)/"
    },
    {
        "Id": 1026,
        "Text": "Closed task",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CloseDate": "/Date(1714006597000)/",
        "CreateDate": "/Date(1714006597078)/",
        "ModifiedDate": "/Date(1714006597078)/"
    }],
    "HasMoreTasks": true
}

Structure TaskList describes task list and has the following properties:

Tasks: task array, each element of the array represents Task structure;
HasMoreTasks: this flag is true when server returned N tasks, use MaximumItemsCount parameter to get more tasks. When server returned all tasks this flag is skipped;

Structure Task describes task and has the following properties:

Id: task identifier;
Text: task text;
Responsible: person, who is responsible for the task, an instance of the structure Person;
DueDate: task due date, this parameter represents date in UTC format without hours, minutes and seconds. If the task does not have due date, the parameter is skipped;
Asap: asap flag, if it equals to false, the parameter is not specified;
Projects: array of task projects;
CloseDate: close date, if the task is opened, this parameter is skipped;
CreateDate: create date;
ModifiedDate: modified date;
ParentTaskId: parent Task Id;

Create Task

A task can be added through the AddTask method. AddTask accepts an AddTaskParams structure as an argument. The only required property of this structure is the Text field for a newly added task. The method AddTask returns an object, containing TaskWithNotes.

URL https://pyrus.com/restapi/addtask is used as REST endpoint with the http method PUT.

Example

PUT https://pyrus.com/restapi/addtask
Header Authorization: Bearer gAAAAA15vmSeoj*******

Request Body

{
    "Text": "Hello world text",
    "ResponsibleId": 400,
    "AddedProjectIds": [1,3],
    "DueDate": "/Date(1713916800000)/"
}

Response Body

{
    "TaskWithNotes": {
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CreateDate": "/Date(1713916800000)/",
        "Author": {
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        },
        "Approvals": [[{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        },
        {
            "Person": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }
        }],
        [{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        }]],
        "Notes": [{
            "CreateDate": "/Date(1713916800000)/",
            "Author": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            "ReassignedTo": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            },
            "AddedProjects": [{
                "Id": 1,"Name": "Root project"
            },
            {
                "Id": 3,
                "Name": "ChildProject",
                "Parent": {
                    "Id": 2,
                    "Name": "Another root project"
                }
            }],
            "DueDateChanged": "/Date(1713916800000)/",
            "ApprovalsAdded": [[{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }],
            [{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }]],
            "Id": 0
        }]
    }
}

Aside from authorization and format errors, the method can return the following custom error codes:

400 Invalid request:

BehavioralEmptyText: New task text must be specified;
BehavioralUnrecognizedAttachmentId: Invalid unique identifier of attachment. User has no attachment with specified ID;

403 Access denied:

BehavioralPersonAccessViolation: No access to person; aside the code parameter, the error structure will contain PersonId parameter. Check, if person is supervisor and his organization is equal to organization where catalog is created;
BehavioralProjectAccessViolation: No access to project; aside the code parameter, the error structure will contain ProjectId parameter. Check if project with specified id exists and it isn't closed;

Structure AddTaskParams and has the following properties:

Text: task text, can not be empty;
ResponsibleId: identifier of the responsible person, if the parameter is not specified, task will be assigned to author;
AddedProjectIds: array of identifiers of creating task;
DueDate: task due date, represents date in UTC format without hours, minutes and seconds;
AddedApprovals: approvals, represents array of steps, each element of which is array of person identifiers;
AttachmentIds: array of unique identifiers of uploaded files, read here about retrieving unique identifiers;
AttachmentUrls: urls of files to attach (like:{"Url":"url","Name":"name"});
Subject: new subject;
ParentTaskId: parent taskId (on create task only);
ScheduleDateTime_Utc: schedule task for provided date and time. If you schedule task for the past date task will be returned into inbox;
IsAnnouncement: Create announcement;

Important

If the ResponsibleId parameter is not specified, a task will be assigned to its author.

Important

When projects are added, the default project workflow is included into its tasks.

Create Form

A form can be added through the AddForm method. AddForm accepts an AddFormParams structure as an argument. The method AddForm returns an object containing TaskWithNotes structure.

URL https://pyrus.com/restapi/addform is used as REST endpoint with the http method PUT.

Example

PUT https://pyrus.com/restapi/addform
Header Authorization: Bearer gAAAAA15vmSeoj*******

Request Body

{
    "TemplateId": 1000,
    "Values": [{
        "FieldId": 1,"Text": "Hello world",
        "Checkmark": 0,
        "Flag": "None"
    },
    {
        "FieldId": 2,
        "Date": "/Date(1714003200000)/",
        "Checkmark": 0,
        "Flag": "None"
    },
    {
        "FieldId": 3,
        "Number": 10.0,
        "Checkmark": 0,
        "Flag": "None"
    },
    {
        "FieldId": 4,
        "Amount": 100.21,"Checkmark": 0,
        "Flag": "None"
    },
    {
        "FieldId": 5,
        "ProjectId": 1001,"Checkmark": 0,
        "Flag": "None"
    },
    {
        "FieldId": 6,
        "PersonId": 300,
        "Checkmark": 0,
        "Flag": "None"
    },
    {
        "FieldId": 7,
        "AssigneeId": 400,
        "Checkmark": 0,
        "Flag": "None"
    },
    {
        "FieldId": 8,
        "Checkmark": "Checked",
        "Flag": "None"
    },
    {
        "FieldId": 9,
        "Checkmark": 0,
        "Flag": "Checked"
    },
    {
        "FieldId": 10,
        "Checkmark": 0,
        "Flag": "None",
        "DueDate": "/Date(1714867200000)/"
    },
    {
        "FieldId": 11,"Checkmark": 0,
        "Flag": "None",
        "Time": {
            "UtcHour": 10,
            "UtcMinute": 53
        }
    },
    {
        "FieldId": 12,
        "Checkmark": 0,
        "Flag": "None",
        "Phone": {
            "Prefix": null,
            "Number": "987654321"
        }
    }]
}

Response Body

{
    "TaskWithNotes": {
        "Id": 1024,
        "Text": "Form:  Hello world",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1714867200000)/",
        "Projects": [{
            "Id": 1000,
            "Name": "Form"
        },
        {
            "Id": 1003,
            "Name": "List item",
            "Parent": {
                "Id": 1002,
                "Name": "List",
                "Parent": {
                    "Id": 1000,
                    "Name": "Form"
                }
            }
        }],
        "CreateDate": "/Date(1713916800000)/",
        "Author": {
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        },
        "Form": [{
            "Field": {
                "Id": 1,"Type": "Text",
                "Name": "Text field"
            },
            "Text": "Hello world"
        },
        {
            "Field": {
                "Id": 2,
                "Type": "Date",
                "Name": "Date field"
            },
            "Date": "/Date(1714003200000)/"
        },
        {
            "Field": {
                "Id": 3,
                "Type": "Number",
                "Name": "Number field"
            },
            "Number": 10,
            "DecimalNumber": null
        },
        {
            "Field": {
                "Id": 4,
                "Type": "Decimal",
                "Name": "Money field"
            },
            "Decimal": 100.21
        },
        {
            "Field": {
                "Id": 5,
                "Type": "Project",
                "Name": "List field"
            },
            "Project": {
                "Id": 1003,
                "Name": "List item",
                "Parent": {
                    "Id": 1002,
                    "Name": "List",
                    "Parent": {
                        "Id": 1000,
                        "Name": "Form"
                    }
                }
            }
        },
        {
            "Field": {
                "Id": 6,
                "Type": "Person",
                "Name": "Contact field"
            },
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        },
        {
            "Field": {
                "Id": 7,
                "Type": "Assignee",
                "Name": "Assignee field"
            },
            "Assignee": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }
        },
        {
            "Field": {
                "Id": 8,
                "Type": "Checkmark",
                "Name": "Checkmark field"
            },
            "Checkmark": "Checked"
        },
        {
            "Field": {
                "Id": 9,
                "Type": "Flag",
                "Name": "Flag field"
            },
            "Flag": "Checked"
        },
        {
            "Field": {
                "Id": 10,
                "Type": "DueDate",
                "Name": "Due date field",
                "DueWithTime": false
            },
            "DueDate": "/Date(1714867200000)/"
        },
        {
            "Field": {
                "Id": 11,"Type": "Time",
                "Name": "Time field"
            },
            "Time": {
                "UtcHour": 10,
                "UtcMinute": 53
            }
        },
        {
            "Field": {
                "Id": 12,
                "Type": "Phone",
                "Name": "Phone field"
            },
            "Phone": {
                "Prefix": "+123",
                "Number": "987654321"
            }
        }]
    }
}

Aside from authorization and format errors, the method can return the following custom error codes:

400 Invalid request:

BehavioralUnrecognizedAttachmentId: Invalid unique identifier of attachment. User has no attachment with specified ID;
BehavioralIrrelevantTemplateFieldIdSpecified: The specified FieldId identificator is incorrect, the field does not exist or has been deleted;

403 Access denied:

BehavioralPersonAccessViolation: No access to person; aside the code parameter, the error structure will contain PersonId parameter. Check, if person is supervisor and his organization is equal to organization where catalog is created;
BehavioralProjectAccessViolation: No access to project; aside the code parameter, the error structure will contain ProjectId parameter. Check if project with specified id exists and it isn't closed;
BehavioralTemplateAccessViolation: No access to template; aside the code parameter, the error structure will contain TemplateId parameter. Check if template exists and user has access to the project associated with this template;

Structure TaskWithNotes describes task with comments and has the following properties:

Id: task identifier;
Text: task text;
Responsible: person, who is responsible for the task, an instance of the structure Person;
DueDate: task due date, this parameter represents date in UTC format without hours, minutes and seconds. If the task does not have due date, the parameter is skipped;
Asap: asap flag, if it equals to false, the parameter is not specified;
Projects: array of task projects;
CloseDate: close date, if the task is opened, this parameter is skipped;
CreateDate: create date;
ModifiedDate: modified date;
ParentTaskId: parent Task Id;
Author: task author, an instance of the structure Person;
Approvals: task approvals, represents array of approval steps, which are arrays of PersonApproval structure. Some approval steps could be skipped, therefore array of PersonApproval will be equal to null;
Form: form values array, can be empty;
Notes: array of task comments, each element of the array represents TaskNote structure. Each task has at least one comment - initial;
IsAnyRejected: flag indicating that one or more approval steps were rejected;
FormTemplateId: form template identifier;

Structure AddFormParams describes new form and has the following properties:

TemplateId: identifier of the template, this field is required;
Values: array of intended values of new form, each item should be of NewFormValue structure type;
AttachmentIds: array of unique identifiers of uploaded files, read here about retrieving unique identifiers;
AttachmentUrls: urls of files to attach;
ResponsibleId: identifier of the responsible person, if the parameter is not specified, task will be assigned to author;
ParentTaskId: parent task id;

Structure NewFormValue describes new form value, contains the required parameter FieldId and one of optional parameters, corresponding to the field type and has the following properties:

FieldId: identifier of the field, required parameter;
Text: text field value;
Number: numeric field value;
ProjectId: list field value (deprecated. Starting from api version 2 ProjectIds should be used);
ProjectIds: multiselect list field values (api version 2);
Date: date field value;
Amount: money field value;
PersonId: contact field value, represents person identifier;
AssigneeId: assignee field value, represents person identifier;
Checkmark: checkmark value, an instance of the enumeration with the following fixed values: Checked, Unchecked;
Flag: flag value, an instance of the enumeration with the following fixed values: None, Checked, Unchecked;
DueDate: task due date field value;
Time: time field value, an instance of the structure Time;
Phone: phone field value, specify only Number parameter, an instance of the structure Phone;
Files: array of unique identifiers of uploaded files, read here about retrieving unique identifiers;
FileUrls: array of file urls to attach (like: {"Url":"url","Name":"name"});
Email: email field value;
RowId: id of current row (api version 2);
Rows: form rows info (api version 2);
CatalogItem: catalog item ID;
ChoiceValue: radio button position;
CurrentStep: current step;
TaskIds: ;

Important

The default field value is set automatically for each field that is not specified in request.

Important

When list type values are added, the default project approvals is included into its form.

Important

Assignee of the task will be set as follows: value of the Assignee filed type it it is specified, otherwise default assignee of a project if the corresponding List field value is specified, otherwise the author of the task.

Important

Due date of the task will be set to the Due date field type value, otherwise it will not be set.

Troubleshooting

Invocation of Pyrus API's methods may response with following error codes:

400 Invalid request:

BadFormatInteger: Invalid value in parameter of integer type. Make sure you are sending integer value as a method parameter;
BehavioralEmptyText: New task text must be specified;
BadFormatDate: Invalid value in date- parameter. Make sure, that the value you put as date- parameter (e.g. DueDate in CreateTask method), has proper format;
BehavioralUnrecognizedAttachmentId: Invalid unique identifier of attachment. User has no attachment with specified ID;
BadFormat: Invalid argument of invoked method. Make sure, that all values, used as arguments for method invocation, have valid type;
BehavioralIrrelevantTemplateFieldIdSpecified: The specified FieldId identificator is incorrect, the field does not exist or has been deleted;

401 No authorization:

AuthorizationErrorInvalidLoginOrSecurityKey: Invalid login or security key. Make sure, that you are using valid login and security key to receive AccessToken(access_token) for background process;
AuthorizationErrorInvalidClientId: Invalid Client ID specified. Make sure that you are using valid Client ID received with registration;
AuthorizationErrorExpiredToken: Authorization token has been expired. Receive new token by performing appropriate procedure for web application or background process;
AuthorizationErrorRevokedToken: Authorization token has been revoked. Receive new token by performing appropriate procedure for web application or background process;
AuthorizationErrorInvalidToken: Invalid authorization token. Receive new token by performing appropriate procedure for web application or background process;
AuthorizationError: Authorization error. Make sure that you've performed authorization process;
AuthorizationErrorTokenNotSpecified: Authorization token not specified. In order to invoke Pyrus API's methods, you need to specify AccessToken(access_token) received during authorization;

403 Access denied:

BehavioralTaskAccessViolation: No access to task. Specified user has no rights to change the task that way;
BehavioralPersonAccessViolation: No access to person; aside the code parameter, the error structure will contain PersonId parameter. Check, if person is supervisor and his organization is equal to organization where catalog is created;
BehavioralProjectAccessViolation: No access to project; aside the code parameter, the error structure will contain ProjectId parameter. Check if project with specified id exists and it isn't closed;
BehavioralTemplateAccessViolation: No access to template; aside the code parameter, the error structure will contain TemplateId parameter. Check if template exists and user has access to the project associated with this template;
BehavioralMaxContentLengthExceeded: Maximum content length exceeded. Size of attachment for non-premium accounts must be less than 5Mb;
UnspecifiedAccessDenied: Access is denied. Сheck if user, that is making an edition of the task, has rights to do it;

Create Comment

Adding comments can be implemented through the AddComment method. It accepts the AddCommentParams structure as a parameter and returns a changed task via an object, contatining TaskWithNotes structure.

URL https://pyrus.com/restapi/addcomment is used as a REST endpoint with the http method PUT.

The example below closes a task

Example

PUT https://pyrus.com/restapi/addcomment
Header Authorization: Bearer gAAAAA15vmSeoj*******

Request Body

{
    "ActivityAction": "MarkAsIrrelevant",
    "TaskId": 1024,
    "Text": "Closing as irrelevant"
}

Response Body

{
    "TaskWithNotes": {
        "Id": 1024,
        "Text": "Hello world text",
        "Responsible": {
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        },
        "DueDate": "/Date(1713916800000)/",
        "Projects": [{
            "Id": 1,"Name": "Root project"
        },
        {
            "Id": 3,
            "Name": "ChildProject",
            "Parent": {
                "Id": 2,
                "Name": "Another root project"
            }
        }],
        "CloseDate": "/Date(1713916800000)/",
        "CreateDate": "/Date(1713916800000)/",
        "ModifiedDate": "/Date(1713916800000)/",
        "Author": {
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        },
        "Approvals": [[{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        },
        {
            "Person": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }
        }],
        [{
            "Person": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }
        }]],
        "Notes": [{
            "CreateDate": "/Date(1713916800000)/",
            "Author": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            "ReassignedTo": {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            },
            "AddedProjects": [{
                "Id": 1,"Name": "Root project"
            },
            {
                "Id": 3,
                "Name": "ChildProject",
                "Parent": {
                    "Id": 2,
                    "Name": "Another root project"
                }
            }],
            "DueDateChanged": "/Date(1713916800000)/",
            "ApprovalsAdded": [[{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            {
                "Id": 400,
                "FirstName": "Bill",
                "LastName": "Smith",
                "Email": "bill.smith@somedomain.edu"
            }],
            [{
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            }]],
            "Id": 0
        },
        {
            "CreateDate": "/Date(1713916800000)/",
            "Author": {
                "Id": 300,
                "FirstName": "John",
                "LastName": "Smith"
            },
            "Text": "Closing as irrelevant",
            "ActivityAction": "MarkAsIrrelevant",
            "Id": 0
        }]
    }
}

Aside from authorization and format errors, the method can return the following custom error codes:

400 Invalid request:

BehavioralUnrecognizedAttachmentId: Invalid unique identifier of attachment. User has no attachment with specified ID;

403 Access denied:

UnspecifiedAccessDenied: Access is denied. Сheck if user, that is making an edition of the task, has rights to do it;
BehavioralTaskAccessViolation: No access to task. Specified user has no rights to change the task that way;
BehavioralPersonAccessViolation: No access to person; aside the code parameter, the error structure will contain PersonId parameter. Check, if person is supervisor and his organization is equal to organization where catalog is created;

Structure AddCommentParams and has the following properties:

TaskId: task identifier, this parameter is required;
Text: comment text, can be null;
ResponsibleId: identifier of responsible person, if the parameter is not specified, task will not be reassigned;
AddedProjectIds: array of identifiers of adding projects;
DueDate: task due date, represents date in UTC format without hours, minutes and seconds;
AddedApprovals: adding approvals, represents array of steps, each element of which is array of person identifiers;
ActivityAction: activity flag, the default value None - dont close or reopen task, an instance of the enumeration with the following fixed values: None - default value, keep task activity unchanged, Complete, MarkAsDuplicate, MarkAsIrrelevant, Reopen;
ApprovalChoice: approval of the comment author, an instance of the enumeration with the following fixed values: Waiting - waiting for approval, this is the default value, Approved, Rejected, Revoked, Acknowledged;
RemovedProjectIds: removing projects, represents array of project identifiers;
ClearDueDate: due date will be cleared when the flag is true;
RemovedApprovals: removing approvals;
RerequestedApprovals: rerequested approvals;
AttachmentIds: array of unique identifiers of uploaded files, read here about retrieving unique identifiers;
FormChanges: array of NewFormValue type, represents changing form values, read here about NewFormValue structure;
ApprovalStage: stage of approval;
ForceWorkflow: apply server workflow;
AttachmentUrls: urls of files to attach (like:{"Url":"url","Name":"name"});
SpentMinutes: spent time in minutes;
Subject: new subject;
ParentTaskId: parent taskId (on create task only);
ScheduleDateTime_Utc: schedule task for provided date and time. If you schedule task for the past date task will be returned into inbox;
IsAnnouncement: Create announcement;

All properties of the structure can be skipped, except TaskId. If the task is not changed and the comment text is empty, a comment will not be created.

Specify the FormChanges property to change values of the task form. If you don`t need to change the field you can skip it`s value in the FormChanges list.

Important

You can not use these type of fields while adding the comment: Assignee and DueDate types. Use the AssigneeId and DueDate properties of the AddCommentParams structure.

Get Profile

To get information about person who granted access to your application, use the GetProfile method. It returns an object, conteining Profile structure.

URL https://pyrus.com/restapi/profile is used as REST endpoint with the http method GET.

Example

GET https://pyrus.com/restapi/profile
Header Authorization: Bearer gAAAAA15vmSeoj*******

Response Body

{
    "Profile": {
        "Id": 400,
        "FirstName": "Bill",
        "LastName": "Smith",
        "Email": "bill.smith@somedomain.edu",
        "Locale": "en-US","CanMakeBackup": false,
        "CanSendLogs": false,
        "CanSyncCatalogs": false,
        "OrganizationId": 0,
        "CanSyncUsers": false
    }
}

Structure Profile describes person profile and has the following properties:

Id: person identifier;
FirstName: person first name, can be empty;
LastName: person last name;
Email: person email;
Locale: person locale, an instance of the enumeration with the following fixed values: ru-RU, en-US, en-GB;
CanSendNotification: can send message;
CanMakeBackup: can make backup;
PersonsInRole: List of Persons in role;
CanSendLogs: can send logs;
Roles: person roles list;
CanSyncCatalogs: can sync catalogs;
OrganizationId: organization id;
OrganizationCatalogId: organization structure catalog id;
CanSyncUsers: can sync users;
CanSendADStructure: ;
CanConfigureIntegrations: ;

Get Contacts

To get a list of contacts, use the GetContacts method. It returns an object, conteining an array of Organization structure.

URL https://pyrus.com/restapi/contacts is used as REST endpoint with the http method GET.

Example

GET https://pyrus.com/restapi/contacts
Header Authorization: Bearer gAAAAA15vmSeoj*******

Response Body

{
    "Organizations": [{
        "Id": 10,
        "Name": "Bill's Ltd.",
        "Persons": [{
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        }]
    }]
}

Structure Organization describes organization and has the following properties:

Id: organization's id;
Name: organization's name;
Persons: persons list;

Structure Person describes person and has the following properties:

Id: person identifier;
FirstName: person first name, can be empty;
LastName: person last name;
Email: person email;
CanSendNotification: can send message;
PersonsInRole: List of Persons in role;

Get Form

Retrieving a form is implemented with the Form method. Form accepts Form Identifier, and returns an FormInfoResponse structure.

URL https://pyrus.com/restapi/form/{formid} is used as REST endpoint with the http method GET. {formid} -Form Identifier.

Example

GET https://pyrus.com/restapi/form/1024
Header Authorization: Bearer gAAAAA15vmSeoj*******

Response Body

{
    "Id": 1024,
    "Name": "Form name",
    "Managers": [{
        "Id": 300,
        "FirstName": "John",
        "LastName": "Smith"
    },
    {
        "Id": 400,
        "FirstName": "Bill",
        "LastName": "Smith",
        "Email": "bill.smith@somedomain.edu"
    }],
    "StepNames": {
        "1": "First step",
        "2": "Second step"
    },
    "Fields": [{
        "Id": 1,"Type": "Text",
        "Name": "Text field"
    },
    {
        "Id": 2,
        "Type": "Date",
        "Name": "Date field"
    },
    {
        "Id": 3,
        "Type": "Number",
        "Name": "Number field"
    },
    {
        "Id": 4,
        "Type": "Decimal",
        "Name": "Money field"
    },
    {
        "Id": 5,
        "Type": "Project",
        "Name": "List field"
    },
    {
        "Id": 6,
        "Type": "Person",
        "Name": "Contact field"
    },
    {
        "Id": 7,
        "Type": "Assignee",
        "Name": "Assignee field"
    },
    {
        "Id": 8,
        "Type": "Checkmark",
        "Name": "Checkmark field"
    },
    {
        "Id": 9,
        "Type": "Flag",
        "Name": "Flag field"
    },
    {
        "Id": 10,
        "Type": "DueDate",
        "Name": "Due date field",
        "DueWithTime": false
    },
    {
        "Id": 11,"Type": "Time",
        "Name": "Time field"
    },
    {
        "Id": 12,
        "Type": "Phone",
        "Name": "Phone field"
    },
    {
        "ChoiceOptions": {
            "0": "No",
            "1": "Yes"
        },
        "Id": 13,
        "Type": "RadioButton",
        "Name": "RadioButton field"
    }]
}

Structure FormInfoResponse and has the following properties:

Id: form ID;
Name: name;
Managers: managers list;
StepNames: step names;
Fields: fields;
PrintForms: print forms;

Field 'Managers' contains the list of Person objects.

Structure Person describes person and has the following properties:

Id: person identifier;
FirstName: person first name, can be empty;
LastName: person last name;
Email: person email;
CanSendNotification: can send message;
PersonsInRole: List of Persons in role;

Returning structure contains 'Fields' field, which is an array of objects each having a type derived from FormField.

Structure FormFieldAuthor and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldCheckmark and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldCreationDate and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldAssignee and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldDate and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldDecimal and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldDueDate and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;
DueWithTime: due with time;

Structure FormFieldFiles and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldFlag and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldNote and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldNumber and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldPerson and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldPhone and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldProject and has the following properties:

MultipleChoice: whether the project field is multiselect;
RootProjectId: root project ID;
Projects: project tree;
Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldText and has the following properties:

DefaultValue: default value;
Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldTime and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldTitle and has the following properties:

IsTable: whether form section title represents a table;
Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldCatalog and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;
CatalogId: catalog ID;
CatalogType: catalog data type;

Structure FormFieldDivider and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldRadioButton and has the following properties:

ChoiceOptions: choice оptions;
Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldActivityStatus and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldApprovalDate and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldApprovalPerson and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldApprovalStep and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Structure FormFieldUnknown and has the following properties:

Id: form field identifier;
Type: form field type identifier, an instance of the enumeration with the following fixed values: Unknown - unknown type, Divider - area divider, ExternalFormAuthor - external form author, Email - email, Catalog - catalog, FileUrls - a field containing one or more file urls, Files - a field containing one or more files, ApprovalStep - no. of approval step this task is currently on, Phone - phone number, Checkmark - checkbox, Note - readonly text field, Time - time field, Assignee - the person responsible for this task, RadioButton - radio button , Author - this task author, ApprovalDate - date when an approval status was set for this task, ActivityStatus - status of this task (closed/open), DueDate - deadline date for this task, CreationDate - the date when this form was created, Title - a form section title, Date - date field, Person - reference to a person, Project - reference to a project, Decimal - money field, Number - number field, Flag - yes/no field, Text - text field, ApprovalPerson - the person who set an approval status for this task, FormLink - radio button ;
Name: form field name;
ParentId: Parent field id;
RequiredFromStep: requered from step;
ImmutableFromStep: immutable from step;
Code: field code;

Please, be aware that some types of field values may not be fully supported via API.

Get All Forms

Retrieving a list of forms is implemented with the Forms method. Forms does not require any params, and returns a collection of FormInfoResponse structure.

URL https://pyrus.com/restapi/forms is used as REST endpoint with the http method GET.

Example

GET https://pyrus.com/restapi/forms
Header Authorization: Bearer gAAAAA15vmSeoj*******

Response Body

{
    "1024": {
        "Id": 1024,
        "Name": "First form",
        "Managers": [{
            "Id": 300,
            "FirstName": "John",
            "LastName": "Smith"
        }],
        "StepNames": {
            "1": "First step",
            "2": "Second step"
        },
        "Fields": [{
            "Id": 1,"Type": "Text",
            "Name": "Text field"
        }]
    },
    "1025": {
        "Id": 1025,
        "Name": "Second form",
        "Managers": [{
            "Id": 400,
            "FirstName": "Bill",
            "LastName": "Smith",
            "Email": "bill.smith@somedomain.edu"
        }],
        "StepNames": {
            "1": "Confirmation step",
            "2": "Result step"
        },
        "Fields": [{
            "Id": 1,"Type": "Text",
            "Name": "Text field"
        }]
    }
}

Returning collection contains the items of structure the same as method Form returns.

Get Form Register

To get form register entries use the GetFormRegister method. The method accepts FormRegisterParams structure as an argument and returns GetFormRegisterReponse structure.

URL https://pyrus.com/restapi/getformregister is used as REST endpoint with the http method POST.

Example

POST https://pyrus.com/restapi/getformregister
Header Authorization: Bearer gAAAAA15vmSeoj*******

Request Body

{
    "FormId": 38354,
    "Filters": [{
        "FieldId": 2,
        "OperatorId": 6,
        "Values": [{
            "FieldId": 2,
            "Checkmark": 0,
            "Flag": "None",
            "Email": "abc"
        }]
    }]
}

Response Body

{
    "Tasks": [{
        "Id": 995,
        "Responsible": {
            "Id": 1730,
            "LastName": "Jackie"
        },
        "CreateDate": "/Date(-62135596800000)/",
        "Form": [{
            "Field": {
                "Id": 1,"Type": "Text",
                "Name": "Num"
            },
            "Text": "6"
        },
        {
            "Field": {
                "Id": 2,
                "Type": "Text",
                "Name": "Email"
            },
            "Text": "abc-updater@mail.com"
        }]
    }]
}

Structure FormRegisterParams describes the GetFormRegister method params and has the following properties:

FormId: form ID;
StartDate: start date (in UTC format without hours, minutes and seconds);
EndDate: end date;
MaxItemCount: maximum number of items to return;
DateMode: date mode;
ActiveOnly: flag that tells server to return active tasks only;
Filters: task filters;

Structure FormRegisterRequestFilter describes task filter and has the following properties:

FieldId: field ID;
OperatorId: operator ID, an instance of the enumeration with the following fixed values: None, Equals, LessThan, GreaterThan, IsIn, Range, MatchPrefix;
Values: filtering values;

Structure NewFormValue describes new form value, contains the required parameter FieldId and one of optional parameters, corresponding to the field type and has the following properties:

FieldId: identifier of the field, required parameter;
Text: text field value;
Number: numeric field value;
ProjectId: list field value (deprecated. Starting from api version 2 ProjectIds should be used);
ProjectIds: multiselect list field values (api version 2);
Date: date field value;
Amount: money field value;
PersonId: contact field value, represents person identifier;
AssigneeId: assignee field value, represents person identifier;
Checkmark: checkmark value, an instance of the enumeration with the following fixed values: Checked, Unchecked;
Flag: flag value, an instance of the enumeration with the following fixed values: None, Checked, Unchecked;
DueDate: task due date field value;
Time: time field value, an instance of the structure Time;
Phone: phone field value, specify only Number parameter, an instance of the structure Phone;
Files: array of unique identifiers of uploaded files, read here about retrieving unique identifiers;
FileUrls: array of file urls to attach (like: {"Url":"url","Name":"name"});
Email: email field value;
RowId: id of current row (api version 2);
Rows: form rows info (api version 2);
CatalogItem: catalog item ID;
ChoiceValue: radio button position;
CurrentStep: current step;
TaskIds: ;

Structure GetFormRegisterReponse and has the following properties:

Tasks: ;
HasMoreTasks: ;
TaskList: returned task list, an instance of the structure TaskList;

Upload File

The Pyrus API allows you to attach files to tasks. It is implemented in two steps:

Upload a single file to the server and get its unique identifier of the type string.
Specify a unique identifier in the AttachmentIds property of AddTaskParams or AddCommentParams as appropriate.

Use the https://pyrus.com/restapi/upload endpoint with the http method POST to upload a file to the server. It returns an UploadedFile structure, which contains only one property of the type string: UploadedFileId, the unique identifier of an uploaded file. Don`t forget to insert an Authorization HTTP Header as in every other request.

Content-Type header

Content-Type header of an upload request must be set to multipart/form-data; boundary=8d2f42366b41441. Boundary is a group of symbols that preceds and follows body of a file. Content-Length header must be specified as well.

Example

POST https://pyrus.com/restapi/upload
Authorization: Bearer gAAA*****
Content-Type: multipart/form-data; boundary=8d2f42366b41441
Host: pyrus.com
Content-Length: 5222
--8d2f42366b41441
Content-Disposition: form-data; name="file"; filename="filename.jpg"
Content-Type: application/octet-stream
// put your file data here
--8d2f42366b41441--

One File Per Request

Upload only one file for each request. If you need to upload more than one file, you should call the upload endpoint several times.

Unique Identifiers

Do not use a structure unique identifier twice. The second attempt will fail.

Aside from authorization and format errors, the method can return the following custom error codes:

403 Access denied:

BehavioralMaxContentLengthExceeded: Maximum content length exceeded. Size of attachment for non-premium accounts must be less than 5Mb;

Authorization for web application

You should implement OAuth 2.0 protocol, so user of your web-application be able to use Pyrus. This type of authorization is most secured. Using this kind of authorization user will send his password through secured channel directly to Pyrus service.

Make following steps for implementation:

1. Register your application, afterwards you'll get your Client ID.
2. Implement a code that will redirect user to https://pyrus.com/oauth with Client ID parameter. On that page user will see form to log into Pyrus. Afterwards user will be redirected to your web-application with code.
3. Request access_token from Pyrus using code.
Now you can use access_token for API methods invocation. When token's time-limit will be exceeded or token will be revoked, you'll get 401 Bad Authorization error. In this case you should make authorization once again (step 2).

How to get access_token?

You have to make several steps, to get access_token and be able to invoke API's method in a name of a Pyrus' user:

1. Redirect user's browser to https://pyrus.com/oauth. Request must contain redirect_uri with an address of access_token receiver. If user isn't logged in yet, he will be advised to log into Pyrus. Also, user have to grant access to his documents in Pyrus.

2. Our server will redirect user to the chosen Url. In case of success, parameter code will contain access code. In case of error, it's description could be found in error parameter.

If your app works not in a web-browser, set redirect_uri to nowebserver. In this case, instead of redirecting to redirect_uri, server will put code parameter in the title and body of response-page .

3. Make POST-request to https://pyrus.com/oauthtoken, you'll get access_token in response. Request should also contain:

client_id: your Client ID
client_secret: your Client Secret
grant_type: authorization_code
redirect_uri: value of redirect_uri, used on step 1
code: code received on step 2

Example

1. Request code:

https://pyrus.com/oauth?client_id=CLIENT_ID&redirect_uri=REDIRECT-URI&response_type=code

REDIRECT-URI must be URL- encoded.

2. Receive it:

http://your-redirect-uri?code=CODE

3. Request access_token:

curl \
-F 'client_id=CLIENT-ID' \
-F 'client_secret=CLIENT-SECRET' \
-F 'grant_type=authorization_code' \
-F 'redirect_uri=YOUR-REDIRECT-URI' \
-F 'code=CODE' \
https://pyrus.com/oauthtoken

4. Receive it:

{
"access_token": "fb2e77d.47a0479900504cb3ab4a1f626d174d2d"
}

Authorization for background process

Perform following steps to implement this kind of authorization:

1. Register your application, afterwards you'll get your Client ID.
2. Receive security key in Settings → Authorized Applications. If you still do not have a security key, click on the button Get new security key. Security key is needed to perform authorization of applications that has no GUI and cannot show a form to enter login and password.
3. Get AccessToken.

How to get AccessToken?

Invoke service method called GetToken which takes GetTokenParams structure as a parameter. It will respond with access_token. This method does not need Authorization http header.

Url https://pyrus.com/restapi/getaccesstoken is used as REST endpoint with the http method POST.

Example

POST https://pyrus.com/restapi/getaccesstoken

Request Body

{
    "Login": "bill.smith@somedomain.edu",
    "SecurityKey": "******",
    "ClientId": "1234abcd-1234-abcd-1234-abcd1234abcd"
}

Response Body

{
    "AccessToken": "gAAAAA15vmSeoj*******"
}

Aside from authorization and format errors, the method can return the following custom error codes:

401 No authorization:

AuthorizationErrorInvalidLoginOrSecurityKey: Invalid login or security key. Make sure, that you are using valid login and security key to receive AccessToken(access_token) for background process;
AuthorizationErrorInvalidClientId: Invalid Client ID specified. Make sure that you are using valid Client ID received with registration;

Structure GetTokenParams describes access token request properties and has the following properties:

Login: user login;
SecurityKey: user security key;
ClientId: application identifier (client_id);
PersonId: person identifier;

Authorization for background process

Perform following steps to implement this kind of authorization:

1. Register your application, afterwards you'll get your Client ID.
2. Receive security key in Settings → Authorized Applications. If you still do not have a security key, click on the button Get new security key. Security key is needed to perform authorization of applications that has no GUI and cannot show a form to enter login and password.
3. Get AccessToken.

How to get AccessToken?

Invoke service method called GetToken which takes GetTokenParams structure as a parameter. It will respond with access_token. This method does not need Authorization http header.

Url https://pyrus.com/restapi/getaccesstoken is used as REST endpoint with the http method POST.

Example

POST https://pyrus.com/restapi/getaccesstoken

Request Body

{
    "Login": "bill.smith@somedomain.edu",
    "SecurityKey": "******",
    "ClientId": "1234abcd-1234-abcd-1234-abcd1234abcd"
}

Response Body

{
    "AccessToken": "gAAAAA15vmSeoj*******"
}

Aside from authorization and format errors, the method can return the following custom error codes:

401 No authorization:

AuthorizationErrorInvalidLoginOrSecurityKey: Invalid login or security key. Make sure, that you are using valid login and security key to receive AccessToken(access_token) for background process;
AuthorizationErrorInvalidClientId: Invalid Client ID specified. Make sure that you are using valid Client ID received with registration;

Structure GetTokenParams describes access token request properties and has the following properties:

Login: user login;
SecurityKey: user security key;
ClientId: application identifier (client_id);
PersonId: person identifier;

Pyrus API v3

Overview

Authorization

Application registration

Get Task

Methods

Content-Type Header

Authorization Header

Compression

Data Formats

Error Handling

Get Task List

Get Inbox Task List

Search Tasks

Get All Tasks

Get All Tasks

Create Task

Important

Important

Create Form

Important

Important

Important

Important

Troubleshooting

Create Comment

Important

Get Profile

Get Contacts

Get Form

Get All Forms

Get Form Register

Upload File

Content-Type header

Example

One File Per Request

Unique Identifiers

Authorization for web application

How to get access_token?

Example

Authorization for background process

How to get AccessToken?

Authorization for background process

How to get AccessToken?