Common response records

Here are described structure of common response records. They have the same shape and rules across the API.

Contact

Table 1. contact fields
Field Type JSON Type Can be null Description

name

String

String

Yes

Contact name. Limited to 50 characters

value

String

String

Yes

Contact string. Limited to 50 characters

type

String

String

No

Only "phone" value is supported at the moment

Address

Table 2. address fields
Field Type JSON Type Can be null Description

formatted

String

String

Yes

Full address as one string

apartment

String

String

Yes

Apartment. Limited to 50 characters

floor

String

String

Yes

Floor. Limited to 50 characters

entrance_no

String

String

Yes

Entrance. Limited to 50 characters

description

String

String

Yes

Optional string description. It usually contains some information helping locating the site. Limited to 500 characters

geolocation

Geolocation

Object

Yes

Geolocation

Worker

Workers are users with permissions to complete jobs.

Table 3. worker fields
Field Type JSON Type Can be null Description

uuid

UUID

String

No

Worker identifier

email

String

String

No

Worker email. It is a globally unique value

Team

Team is a group workers.

Table 4. team fields
Field Type JSON Type Can be null Description

uuid

UUID

String

No

Team identifier

team

String

String

No

Team name

Assignee

Jobs and job templates can have assignees. It is a reference to either a worker or a team.

team and worker fields are mutually exclusive.
Table 5. assignee fields
Field Type JSON Type Can be null Description

team

Team

Object

No

Team

worker

Worker

Object

No

Worker

Assignee UUID

team_uuid and worker_uuid fields are mutually exclusive.
Table 6. assignee fields
Field Type JSON Type Can be null Description

team_uuid

UUID

String

No

Team identifier

worker_uuid

UUID

String

No

Worker identifier

Client

Table 7. client fields
Field Type JSON Type Can be null Description

uuid

UUID

String

No

Client identifier

external_id

String

String

Yes

External identifier

Territory

Territory is an area where an assignee or a team operates.

Table 8. territory fields
Field Type JSON Type Can be null Description

uuid

UUID

String

No

Territory identifier

name

String

String

No

Territory name

Skill

Worker skills are used to filter possible assignees for a job.

Table 9. skill fields
Field Type JSON Type Can be null Description

uuid

UUID

String

No

Skill identifier

name

String

String

No

Skill name

Dictionary item

Dictionary is a list of elements that can be used as field values.

Table 10. dictionary_value fields
Field Type JSON Type Can be null Description

uuid

UUID

String

No

Item identifier

name

String

String

No

Item name

Resolution

Resolution is a result of a finished job.

Table 11. resolution fields
Field Type JSON Type Can be null Description

uuid

UUID

String

No

Resolution identifier

name

String

String

No

Resolution name

successful

Boolean

Boolean

No

Whether the resolution is successful or not

comment

String

String

Yes

Comment filled out by a field worker. This field is only present only as part of finished job

Custom field

Custom fields can be added to jobs by using templates. There are two sections containing custom fields: custom_fields and report_fields. custom_fields is a list of fields that are filled by the dispatcher, they are avialble for the assignee in the read-only mode. report_fields are filled via the mobile app. Fields can be rendered as various UI element (e.g. select/dropdown list, text input, etc) and have different data types (pick list value, string, file, and so on).

JSON type of value depends on field_type and data_type.
Field Type JSON Type Can be null Description

uuid

UUID

String

No

Field identifier

name

String

String

No

Field name

field_type

String

String

No

Field type

data_type

String

String

No

Data type

required

Boolean

Boolean

No

Whether this field must be filled.
For custom_fields the dispatcher will be asked to enter the value to create a job.
For report_fields the assignee will be asked to fill the value to finish the job successfully

value

Mixed

Mixed

Yes

Value of the field. This key is always present for jobs. For job templates, it’s only present for custom fields that can be pre-filled (e.g. file fields)

filled_at

Datetime

String

No

When the values was set. This field is only present for report_fields with non-empty value

Field types

  • image

  • input

  • action

  • checkbox

  • textarea

  • barcode

  • file

  • dictionary

  • button

  • link

  • currency

  • datetime_picker

  • date_picker

  • signature

Data types

  • string

  • integer

  • decimal

  • boolean

  • attachment

  • dictionary

  • url

  • currency

  • datetime

  • date

Supported combinations

Different combinations supported differently in custom_fields and report_fields. Below, “CF” and “RF” stand for whether the combination may appear in custom_fields and report_fields respectively.

field_type data_type CF RF Type of value Can be null Description

input

string

Yes

Yes

String

Yes

input

integer

Yes

Yes

String

Yes

Integers are passed as strings to avoid overflow in JSON numbers

input

decimal

Yes

Yes

String

Yes

Decimals are passed as strings to avoid overflow in JSON numbers

currency

currency

Yes

Yes

String

Yes

Currency fields have "currency" key which contains ISO 4217 code in lower case (e.g. "usd")

textarea

string

No

Yes

String

Yes

action

boolean

No

Yes

Boolean

Yes

Whether the action is marked as done

checkbox

boolean

No

Yes

Boolean

Yes

Yes-or-no field

barcode

string

No

Yes

String

Yes

Barcode/QR-code value

file (custom)

attachment

Yes

No

String

Yes

File URL

file (report)

attachment

No

Yes

[String]

No

List of file URLs

image

attachment

No

Yes

[String]

No

List of file URLs

dictionary

dictionary

Yes

Yes

Dictionary item

Yes

link

url

Yes

Yes

String

Yes

Report fields with link type displayed as buttons openning WebView in the app

datetime_picker

datetime

Yes

Yes

String

Yes

ISO 8601-encoded datetime value

date_picker

date

Yes

Yes

String

Yes

ISO 8601-encoded date value