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

Permissions

User permissions object. It describes what actions a user can perform.

Field Type JSON Type Required Can be null Description

web

Record

Object

No

No

Web application permissions

mobile

Record

Object

No

No

Mobile application permissions

Example of permissions object

{
  "web": {
    "login": true,
    "jobs": {
      "view": true,
      "edit": true,
      "delete": true
    },
    "clients": {
      "view": true,
      "edit": true
    },
    "schedule": {
      "view": true,
      "edit": true
    },
    "map": {
      "edit": false
    },
    "shifts": {
      "edit": false
    },
    "teams": {
      "view": true,
      "edit": true
    },
    "jobs_export": false
  },
  "mobile": {
    "login": true,
    "jobs": {
      "view": true,
      "complete": true
    }
  }
}

Product

Object containing information about a product.

Field Type JSON Type Can be null Description

uuid

UUID

String

No

Product identifier

name

String

String

No

Product name

external_id

String

String

Yes

External identifier

Service

Object containing information about a service.

Field Type JSON Type Can be null Description

uuid

UUID

String

No

Service identifier

name

String

String

No

Service name

external_id

String

String

Yes

External identifier

Unit

Object containing information about a unit.

Field Type JSON Type Can be null Description

uuid

UUID

String

No

Unit identifier

name

String

String

No

Unit name

code

String

String

No

Unit code

external_id

String

String

Yes

External identifier

Category

Object containing information about a category.

Field Type JSON Type Can be null Description

uuid

UUID

String

No

Category identifier

name

String

String

No

Category name

external_id

String

String

Yes

External identifier

Available catalog entity

Field Type JSON Type Required Can be null Description

type

String

String

Yes

No

Either category or service

category

Category

Object

No

No

Category info. Only returned for categories

service

Service

Object

No

No

Service info. Only returned for services

required

Boolean

Boolean

No

No

Whether the service is required. Only returned for services

pre_ordered

Boolean

Boolean

No

No

Whether the service is pre-ordered. Only returned for services

Ordered service

Field Type JSON Type Can be null Description

service

Service

Object

No

Service info

required

Boolean

Boolean

No

Whether the service is required

ordered_service_uuid

UUID

String

No

Ordered service identifier (differs from service.uuid)

Provided service

Field Type JSON Type Required Can be null Description

service

Service

Object

Yes

No

Service info

ordered_service_uuid

UUID

String

No

No

Ordered service identifier

provided_service_uuid

UUID

String

Yes

No

Provided service identifier (differs from service.uuid and ordered_service_uuid)

currency

String

String

Yes

No

ISO 4217 code

price

String

String

No

Yes

Decimal in string format

amount

String

String

No

Yes

Decimal in string format

Used material

Field Type JSON Type Required Can be null Description

product

Product

Object

Yes

No

Product info

unit

Unit

Object

YEs

No

Unit info

service

Service

Object

Yes

No

Service info

provided_service_uuid

UUID

String

Yes

No

Provided service identifier

currency

String

String

Yes

No

ISO 4217 code

quantity

String

String

Yes

No

Decimal in string format

price

String

String

No

Yes

Decimal in string format (for one item)

amount

String

String

No

Yes

Decimal in string format (price * quantity)