API Okdesk

This documentation describes the existing methods of Okdesk API.

All queries require api_token parameter (authorization key). The authorization key can be generated in the API section of your Okdesk account settings.

Companies ¶

Company search

GET`/api/v1/companies/{?api_token,name,phone,id,crm_1c_id,search_string}`

The search is carried out by the exact match of the name or additional name of the company, phone and internal ID, by the occurrence of a substring in the value of the object ID in 1C or substring

Restriction of access rights

Search of the company will be completed only if the key-linked agent has access to the list of companies in accordance with the access rights settings. This method is not available for contact-associated keys.

Please note

When transferring the search_string parameter, the other parameters are not considered
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace

URI example

GET https://<account>.okdesk.com/api/v1/companies/?api_token=3e9a214215f493c4&name=Okdesk&phone=+7(499)703-47-20&id=1040&crm_1c_id=35067c4b23a8&search_string=desk

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
name: string (optional) Example: Okdesk
Name
phone: string (optional) Example: +7(499)703-47-20
Phone number
id: integer (optional) Example: 1040
Internal Company ID
crm_1c_id: string (optional) Example: 35067c4b23a8
Object ID in 1C
search_string: string (optional) Example: desk
Target substring

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "id": 1040,
    "name": "Okdesk",
    "additional_name": "Help Desk system for service companies",
    "site": "http://okdesk.com",
    "email": "info@okdesk.com",
    "phone": "+7(499)703-47-20",
    "crm_1c_id": "35067c4b23a8",
    "active": true,
    "address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
    "coordinates": [
        53.2184321,
        44.9998082
    ],
    "comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions."
    "observers":
        [
            {
              "id": 2,
              "name": "Fred Bloggs"
            },
            {
              "id": 1,
              "name": "John Smith"
            }
        ],
    "contacts": [],
    "default_assignee":
        {
            "id": 1,
            "name": "John Smith"
        },
    "default_assignee_group":
        {
            "id": 1,
            "name": "Monitoring Group",
            "active": true,
            "description": ""
        },
    "category":
        {
            "id": 3,
            "code": "vipclient",
            "name": "VIP-client",
            "color": "#5cb85c"
        },
    "attachments": [
        {
          "id": 8,
          "attachment_file_name": "photo.jpg",
          "description": "Photo of malfunction",
          "attachment_file_size": 4149,
          "is_public": false,
          "created_at": "2016-09-30T09:28:50.499+03:00"
        }
    ],
    "parameters": [
        {
            "code": "attr1",
            "name": "Document No.",
            "field_type": "ftstring",
            "value": "2368590"
        },
        {
            "code": "attr2",
            "name": "Commencement date",
            "field_type": "ftdate",
            "value": "2019-02-06"
        },
        {
            "code": "attr3",
            "name": "Date of the next call",
            "field_type": "ftdatetime",
            "value": "2019-02-21T14:00:00.000+03:00"
        },
        {
            "code": "attr4",
            "name": "VIP Service",
            "field_type": "ftcheckbox",
            "value": true
        },
        {
            "code": "attr5",
            "name": "Type of activity",
            "field_type": "ftselect",
            "value": "Software"
        },
        {
            "code": "attr6",
            "name": "Types of premises",
            "field_type": "ftmultiselect",
            "value": [
                "Head office",
                "Recreation area"
            ]
        }
    ]
}

Creating a company

POST`/api/v1/companies/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	required	Name
additional_name	string	optional	Additional company name
site	string	optional	Company website
email	string	optional	Company contact e-mail address
phone	string	optional	Company contact phone
address	string	optional	Company address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc.
coordinates	array of float	optional	Company coordinates
comment	string	optional	Additional company info
observer_ids	array of integer	optional	User ID array for company viewers
default_assignee_id	integer	optional	ID of the responsible agent assigned for this company by default
default_assignee_group_id	integer	optional	ID of the responsible agent group
category_code	string	optional	Client category code
crm_1c_id	string	optional	Object ID in 1C, required to integrate with 1C; is not displayed in the web interface
custom_parameters	associative array	optional	Company extended attributes

Restriction of access rights

Creation of a company is available to agents in accordance with the settings of access rights. This method is not available for contact-associated keys.

Please note

The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude).

URI example

POST https://<account>.okdesk.com/api/v1/companies/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "company": {
    "name": "Okdesk",
    "additional_name": "Help Desk system for service companies",
    "site": "http://okdesk.com",
    "email": "info@okdesk.com",
    "phone": "+7(499)703-47-20",
    "address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
    "observer_ids": [
      1,
      2
    ],
    "default_assignee_id": 1,
    "default_assignee_group_id": 1,
    "category_code": "client",
    "crm_1c_id": "67067c3a29a8",
    "custom_parameters": {
      "code1": "123456789",
      "code2": "2019-02-15",
      "code3": true
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1040,
  "name": "Okdesk",
  "additional_name": "Help Desk system for service companies",
  "site": "http://okdesk.com",
  "email": "info@okdesk.com",
  "phone": "+7(499)703-47-20",
  "address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "observers": [
    {
      "id": 2,
      "name": "Fred Bloggs"
    },
    {
      "id": 1,
      "name": "John Smith"
    }
  ],
  "contacts": [],
  "default_assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "default_assignee_group": {
    "id": 1,
    "name": "Monitoring Group",
    "active": true,
    "description": ""
  },
  "category": {
    "id": 2,
    "code": "client",
    "name": "Client",
    "color": "#5cb85c"
  },
  "attachments": [],
  "parameters": [
    {
      "code": "code1",
      "name": "Document No.",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Commencement date",
      "field_type": "ftdate",
      "value": "2019-02-15"
    },
    {
      "code": "code3",
      "name": "VIP Service",
      "field_type": "ftcheckbox",
      "value": true
    }
  ]
}

Editing the company

PATCH`/api/v1/companies/{company_id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	optional	Name
additional_name	string	optional	Additional company name
site	string	optional	Company website
email	string	optional	Company contact e-mail address
phone	string	optional	Company contact phone
address	string	optional	Company address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc.
coordinates	array of float	optional	Company coordinates
comment	string	optional	Additional company info
observer_ids	array of integer	optional	User ID array for company viewers
default_assignee_id	integer	optional	ID of the responsible agent assigned for this company by default
default_assignee_group_id	integer	optional	ID of the responsible agent group
category_code	string	optional	Client category code
crm_1c_id	string	optional	Object ID in 1C, required to integrate with 1C; is not displayed in the web interface
custom_parameters	associative array	optional	Company extended attributes

Restriction of access rights

Editing of the company will be completed only if the key-linked agent has the rights to view the company and edit the company attributes in accordance with the access rights settings. This method is not available for contact-associated keys.

Please note

The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude).

URI example

PATCH https://<account>.okdesk.com/api/v1/companies/4?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
company_id: integer (required) Example: 4
Company ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "company": {
    "name": "Okdesk",
    "additional_name": "Help Desk system for service companies",
    "site": "http://okdesk.com",
    "email": "info@okdesk.com",
    "phone": "+7(499)703-47-20",
    "address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
    "observer_ids": [
      1,
      2
    ],
    "default_assignee_id": 1,
    "default_assignee_group_id": 1,
    "category_code": "vipclient",
    "crm_1c_id": "67067c3a29a8",
    "custom_parameters": {
      "code2": "2019-02-22"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "id": 1040,
    "name": "Okdesk",
    "additional_name": "Help Desk system for service companies",
    "site": "http://okdesk.com",
    "email": "info@okdesk.com",
    "phone": "+7(499)703-47-20",
    "address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
    "coordinates": [
        53.2184321,
        44.9998082
    ],
    "comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions."
    "crm_1c_id": "67067c3a29a8",
    "active": true,
    "observers":
        [
            {
              "id": 2,
              "name": "Fred Bloggs"
            },
            {
              "id": 1,
              "name": "John Smith"
            }
        ],
    "contacts": [],
    "default_assignee":
        {
            "id": 1,
            "name": "John Smith"
        },
    "default_assignee_group":
        {
            "id": 1,
            "name": "Monitoring Group",
            "active": true,
            "description": ""
        },
    "category":
        {
            "id": 2,
            "code": "vipclient",
            "name": "VIP-client",
            "color": "#5cb85c"
        },
    "attachments": [
        {
          "id": 8,
          "attachment_file_name": "photo.jpg",
          "description": "Photo of malfunction",
          "attachment_file_size": 4149,
          "is_public": false,
          "created_at": "2016-09-30T09:28:50.499+03:00"
        }
    ],
    "parameters": [
        {
            "code": "code1",
            "name": "Document No.",
            "field_type": "ftstring",
            "value": "123456789"
        },
        {
            "code": "code2",
            "name": "Commencement date",
            "field_type": "ftdate",
            "value": "2019-02-22"
        },
        {
            "code": "code3",
            "name": "VIP Service",
            "field_type": "ftcheckbox",
            "value": true
        }
    ]
}

Obtaining list by parameters

GET`/api/v1/companies/list{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
category_ids	array of integer	optional	Array of company category IDs (set the value “0” to the parameter to show companies without category). Example: category_ids[]=1
default_assignee_ids	array of integer	optional	Array of company responsible agent IDs (set the value “0” to the parameter to show companies without a responsible agent). Example: default_assignee_ids[]=1
default_assignee_group_ids	array of integer	optional	Array of company responsible group IDs (set the value “0” to the parameter to show companies without a responsible group). Example: default_assignee_group_ids[]=1
observer_ids	array of integer	optional	Array of company viewer IDs (set the value “0” to the parameter to show companies without viewers). Example: observer_ids[]=1
observer_group_ids	array of integer	optional	Array of company viewer group IDs (set the value “0” to the parameter to show companies without viewer groups). Example: observer_group_ids[]=1
created_since	string	optional	The date the company was created in the account’s time zone (From) Example: created_since=2019-05-25
created_until	string	optional	The date the company was created in the account’s time zone (Until) Example: created_until=2019-05-25
custom_parameters	associative array	optional	Associative array of Extended attribute code pairs: Value or set of values
name	string	optional	Name Example: name=Okdesk
additional_name	string	optional	Additional company name Example: additional_name=Help Desk system for service companies
crm_1c_id	string	optional	Object ID in 1C Example: crm_1c_id=35067c4b23a8
page	associative array	optional	Associative array of parameters for a per-page display of the company list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the company starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the company id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the company’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the company’s lowest id. Example: page[direction]=forward

Restriction of access rights

Retrieving of the list of companies will be completed only if the key-linked agent has access to the list of companies in accordance with the access rights settings. This method is not available for contact-associated keys.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 companies created will be returned.

Valid values of extended attributes:

Parameter type	Type	Description
Date	string	There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12
Date/time	string	There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12
Checkbox	string	Two values – true and false – are available. Example: custom_parameters[checkbox_code]=true
List item	array of string	An array of list values. Example: custom_parameters[list_code][]=list_value
List item set	array of string	An array of list values. Example: custom_parameters[list_code][]=list_value
String	string	String type value. Example: custom_parameters[string_code]=string_value

An example of a query with the company list per-page display parameters:

https://<account>.okdesk.com/api/v1/companies/list?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/companies/list?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 22,
    "name": "Mom and Pop",
    "additional_name": "Help Desk system for service companies",
    "active": true,
    "parameters": [
      {
        "code": "code1",
        "name": "Document No.",
        "field_type": "ftstring",
        "value": "123456789"
      },
      {
        "code": "code2",
        "name": "Commencement date",
        "field_type": "ftdate",
        "value": "2019-02-22"
      },
      {
        "code": "code3",
        "name": "VIP Service",
        "field_type": "ftcheckbox",
        "value": true
      }
    ]
  },
  {
    "id": 12,
    "name": "Acme Ltd.",
    "additional_name": "Help Desk system for service companies",
    "active": true,
    "parameters": [
      {
        "code": "code1",
        "name": "Document No.",
        "field_type": "ftstring",
        "value": "987654321"
      },
      {
        "code": "code2",
        "name": "Commencement date",
        "field_type": "ftdate",
        "value": "2020-02-22"
      },
      {
        "code": "code3",
        "name": "VIP Service",
        "field_type": "ftcheckbox",
        "value": false
      }
    ]
  },
  {
    "id": 10,
    "name": "Okdesk",
    "additional_name": "Help Desk system for service companies",
    "active": true,
    "parameters": [
      {
        "code": "code1",
        "name": "Document No.",
        "field_type": "ftstring",
        "value": "123456"
      },
      {
        "code": "code2",
        "name": "Commencement date",
        "field_type": "ftdate",
        "value": "2021-02-22"
      },
      {
        "code": "code3",
        "name": "VIP Service",
        "field_type": "ftcheckbox",
        "value": true
      }
    ]
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "created_until": [
      "Invalid date"
    ],
    "observer_ids": {
      "1": [
        "must be an integer"
      ]
    },
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Obtaining a file of a company

GET`/api/v1/companies/{company_id}/attachments/{attachment_id}{?api_token}`

Restriction of access rights

The file information will be provided only if the user associated with the key has rights to view the company and the file list. This method is not available for contact-associated keys.

Please note

File size (attachment_file_size) measured in bytes. Attachment URL is temporary. It expires after 30 seconds of its creation.

URI example

GET https://<account>.okdesk.com/api/v1/companies/166/attachments/22?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
company_id: integer (required) Example: 166
company ID.
attachment_id: integer (required) Example: 22
File ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 22,
  "attachment_file_name": "image.jpg",
  "description": "",
  "attachment_file_size": 7955,
  "is_public": true,
  "created_at": "2019-10-29T17:31:30.675+03:00",
  "attachment_url": "https://static.okdesk.com/attachments/attachments/000/000/150/original/hqdefault.jpg"
}

Archiving companies

PATCH`/api/v1/companies/{id}/activations{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
active	boolean	required	Company activation status

Restriction of access rights

Company archiving is available to agents in accordance with the settings of access rights.

URI example

PATCH https://<account>.okdesk.com/api/v1/companies/1040/activations?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 1040
company ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "id": 1040,
    "name": "Okdesk",
    "additional_name": "Help Desk system for service companies",
    "site": "http://okdesk.com",
    "email": "info@okdesk.com",
    "phone": "+7(499)703-47-20",
    "address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
    "coordinates": [
        53.2184321,
        44.9998082
    ],
    "comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions."
    "crm_1c_id": "67067c3a29a8",
    "active": true,
    "observers":
        [
            {
              "id": 2,
              "name": "Fred Bloggs"
            },
            {
              "id": 1,
              "name": "John Smith"
            }
        ],
    "contacts": [],
    "default_assignee":
        {
            "id": 1,
            "name": "John Smith"
        },
    "default_assignee_group":
        {
            "id": 1,
            "name": "Monitoring Group",
            "active": true,
            "description": ""
        },
    "category":
        {
            "id": 2,
            "code": "vipclient",
            "name": "VIP-client",
            "color": "#5cb85c"
        },
    "attachments": [
        {
          "id": 8,
          "attachment_file_name": "photo.jpg",
          "description": "Photo of malfunction",
          "attachment_file_size": 4149,
          "is_public": false,
          "created_at": "2016-09-30T09:28:50.499+03:00"
        }
    ],
    "parameters": [
        {
            "code": "code1",
            "name": "Document No.",
            "field_type": "ftstring",
            "value": "123456789"
        },
        {
            "code": "code2",
            "name": "Commencement date",
            "field_type": "ftdate",
            "value": "2019-02-22"
        },
        {
            "code": "code3",
            "name": "VIP Service",
            "field_type": "ftcheckbox",
            "value": true
        }
    ]
}

Employees ¶

Creating an agent

POST`/api/v1/employees/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
last_name	string	optional	Last name
first_name	string	required	First name
patronymic	string	optional	Middle name
position	string	optional	Title
email	string	required	Agent E-mail
login	string	required	Agent login
password	string	required	Password
phone	string	optional	Phone number
telephony_number	string	optional	Extension number
comment	string	optional	Additional information on the agent
group_ids	associative array	optional	Set of agent group IDs
role_ids	associative array	required	Set of agent role IDs

Restriction of access rights

The method is only available for keys associated with the user role “Administrator”.

Please note

This method creates an inactive agent.

URI example

POST https://<account>.okdesk.com/api/v1/employees/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "employee": {
    "first_name": "Joe",
    "last_name": "Meatball",
    "patronymic": "Smith",
    "position": "Manager",
    "email": "employee@okdesk.com",
    "login": "joe_manager",
    "password": "12345678",
    "role_ids": [
      1
    ],
    "group_ids": [
      2,
      3
    ],
    "phone": "+79459999999",
    "telephony_number": "0321",
    "comment": "Senior Manager is responsible for Strategic Planning"
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "10",
  "last_name": "Meatball",
  "first_name": "Joe",
  "patronymic": "Smith",
  "position": "Manager",
  "active": false,
  "email": "employee@okdesk.com",
  "login": "joe_manager",
  "phone": "+79459999999",
  "telephony_number": "0321",
  "mobile_last_seen": null,
  "last_seen": null,
  "comment": "Senior Manager is responsible for Strategic Planning",
  "groups": [
    {
      "id": 2,
      "name": "Quality control department"
    },
    {
      "id": 3,
      "name": "Sales department"
    }
  ],
  "roles": [
    {
      "id": 1,
      "name": "Admin"
    }
  ]
}

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "employee": {
    "last_name": "Meatball",
    "email": "employee",
    "login": 123,
    "password": "12345678",
    "role_ids": [
      1
    ],
    "phone": "+79459999999"
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "first_name": [
      "is missing"
    ],
    "email": [
      "has invalid format"
    ],
    "login": [
      "must be a string"
    ]
  }
}

Editing an agent

PATCH`/api/v1/employees/{employee_id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
last_name	string	optional	Last name
first_name	string	optional	First name
patronymic	string	optional	Middle name
position	string	optional	Title
email	string	optional	Agent E-mail
login	string	optional	Agent login
password	string	optional	Password
phone	string	optional	Phone number
telephony_number	string	optional	Extension number
comment	string	optional	Additional information on the agent
group_ids	associative array	optional	Set of agent group IDs
role_ids	associative array	optional	Set of agent role IDs

Restriction of access rights

The method is only available for keys associated with the user role “Administrator”.

Please note

When sending an empty array in the group_ids parameter, the agent is removed from all groups.

URI example

PATCH https://<account>.okdesk.com/api/v1/employees/10?api_token=3e9a214215f493c4

URI parameters

HideShow

employee_id: integer (required) Example: 10
Agent ID.
api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "employee": {
    "first_name": "Joe",
    "last_name": "Meatball",
    "patronymic": "Smith",
    "position": "Manager",
    "email": "employee@okdesk.com",
    "login": "joe_manager",
    "password": "12345678",
    "role_ids": [
      1,
      2
    ],
    "group_ids": [
      4
    ],
    "phone": "+79459999999",
    "telephony_number": "0321",
    "comment": "Senior Manager is responsible for Strategic Planning"
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 10,
  "last_name": "Meatball",
  "first_name": "Joe",
  "patronymic": "Smith",
  "position": "Manager",
  "active": false,
  "email": "employee@okdesk.com",
  "login": "joe_manager",
  "phone": "+79459999999",
  "telephony_number": "0321",
  "comment": "Senior Manager is responsible for Strategic Planning",
  "groups": [
    {
      "id": 4,
      "name": "Analytics department"
    }
  ],
  "roles": [
    {
      "id": 1,
      "name": "Admin"
    },
    {
      "id": 2,
      "name": "Manager"
    }
  ]
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Agent activation

PATCH`/api/v1/employees/{id}/activations{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
active	boolean	required	Agent activation status

Restriction of access rights

The method is only available for keys associated with the user role “Administrator”.

URI example

PATCH https://<account>.okdesk.com/api/v1/employees/10/activations?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 10
agent ID.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 10,
  "last_name": "Meatball",
  "first_name": "Joe",
  "patronymic": "Smith",
  "position": "Manager",
  "active": false,
  "email": "employee@okdesk.com",
  "login": "joe_manager",
  "phone": "+79459999999",
  "telephony_number": "0321",
  "mobile_last_seen": null,
  "last_seen": null,
  "comment": "Senior Manager is responsible for Strategic Planning",
  "groups": [
    {
      "id": 4,
      "name": "Analytics department"
    }
  ],
  "roles": [
    {
      "id": 1,
      "name": "Admin"
    },
    {
      "id": 2,
      "name": "Manager"
    }
  ]
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Receiving agents roles

GET`/api/v1/employees/roles{?api_token}`

Restriction of access rights

The method is only available for keys associated with the user roles “Administrator”.

URI example

GET https://<account>.okdesk.com/api/v1/employees/roles?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Receiving agents groups

GET`/api/v1/employees/groups{?api_token}`

Restriction of access rights

The method is only available for keys associated with the user roles “Administrator”.

URI example

GET https://<account>.okdesk.com/api/v1/employees/groups?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "name": "Technical support",
    "active": true,
    "description": "",
    "employees": [
      {
        "id": 3020,
        "first_name": "John",
        "last_name": "Smith",
        "patronymic": "",
        "login": "john_smith"
      },
      {
        "id": 3030,
        "first_name": "Fred",
        "last_name": "Bloggs",
        "patronymic": "",
        "login": "fred_bloggs"
      }
    ]
  },
  {
    "id": 2,
    "name": "Managers",
    "active": true,
    "description": "",
    "employees": [
      {
        "id": 3030,
        "first_name": "Fred",
        "last_name": "Bloggs",
        "patronymic": "",
        "login": "fred_bloggs"
      }
    ]
  }
]

Receiving agent route

GET`/api/v1/employees/routes/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
employee_id	integer	required	ID Employee
date_from	string	optional	Date of coordinate receipt in the account time zone (From) Example: date_from=2021-05-25 00:00
date_to	string	optional	Date of coordinate receipt in the account time zone (To) Example: date_to=2021-05-25 00:00
page	associative array	optional	Associative array of parameters for per-page display of agent routes (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	ID coordinates from which the selection of records starts. By default (if the direction parameter is not specified) selectionstarts from the value from_id from new coordinates to the older ones Example: page[from_id]=10
direction	string	optional	Direction of selection. Two values are available: reverse, forward. reverse - the selection is carried out starting from the value from_id, from the new coordinates to the older ones. forward - the selection is performed starting from the value from_id, from the old coordinates to the newer ones. If the from_id parameter is absent, the selection is performed from the new coordinates to the older ones. Example: page[direction]=forward

Restriction of access rights

The method is only available for keys associated with the user roles “Administrator”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 coordinates received will be returned.

An example of a query with the agent coordinates per-page display parameters:

https://<account>.okdesk.ru/api/v1/employees/routes/?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=5&page[direction]=forward&employee_id=1&date_from=2021-01-23 00:00&date_to=2021-01-30 00:00

URI example

GET https://<account>.okdesk.com/api/v1/employees/routes/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 5,
    "received_at": "2021-01-29T12:27:41.000+03:00",
    "latitude": 53.1689031,
    "longtitude": 45.0079597
  },
  {
    "id": 6,
    "received_at": "2021-01-29T12:30:36.000+03:00",
    "latitude": 53.1689036,
    "longtitude": 45.0079447
  },
  {
    "id": 7,
    "received_at": "2021-01-29T14:06:26.000+03:00",
    "latitude": 53.16882,
    "longtitude": 45.0079635
  }
]

Obtaining list by parameters

GET`/api/v1/employees/list/{?api_token}`

Valid per-page display parameters:

Name	Type	Mandatory	Description
role_ids	array of integer	optional	Array of agent roles IDs. Example: role_ids[]=1
active	string	optional	Activity status. Takes true or false value

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the agent starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the agent id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the agent’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the agent’s lowest id. Example: page[direction]=forward

Restriction of access rights:

The method is only available for keys associated with the user role “Administrator”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 agents created will be returned.

An example of a query with the agent list per-page display parameters:

https://<account>.okdesk.com/api/v1/employees/list?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/employees/list/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": "10",
    "last_name": "Meatball",
    "first_name": "Joe",
    "patronymic": "Smith",
    "position": "Manager",
    "active": false,
    "email": "employee@okdesk.com",
    "login": "joe_manager",
    "phone": "+79459999999",
    "telephony_number": "0321",
    "mobile_last_seen": "2023-11-30T15:11:09.095+03:00",
    "last_seen": "2023-11-30T15:08:09.095+03:00",
    "comment": "Senior Manager is responsible for Strategic Planning",
    "groups": [
      {
        "id": 4,
        "name": "Analytics department"
      }
    ],
    "roles": [
      {
        "id": 1,
        "name": "Admin"
      }
    ]
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
    "errors": {
        "active": [
            "must be one of: true, false"
        ],
        "role_ids": {
            0: [
                "must be an integer"
            ],
        }
    }
}

Contacts ¶

Contact search

GET`/api/v1/contacts/{?api_token,id,email,phone,search_string}`

The search is carried out by the exact match of the contact’s email or additional email address, contact’s Telegram account, by matching the last N digits of the contact’s phone or mobile phone, or substring

Restriction of access rights

Search of the contact will be completed only if the key-linked agent has access to the contacts list in accordance with the access rights settings. The authentication_code, login and access_level parameters are available only to agents with the right to view contact’s access details. The last_seen parameter is available only for agents with the Administrator role.

Please note

When transferring the search_string parameter, the other parameters are not considered
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace
The last_seen parameter has a 5-minute accuracy.
The contact search by phone or mobile phone number is carried out by matching last N digits ignoring separator characters (parentheses, hyphens, and others, that is, only numbers are taken into account). If more than 10 digits are sent, the last 10 will be used for search.

URI example

GET https://<account>.okdesk.com/api/v1/contacts/?api_token=3e9a214215f493c4&id=1024&email=employee@okdesk.com&phone=83214567788&search_string=desk

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (optional) Example: 1024
Internal contact ID
email: string (optional) Example: employee@okdesk.com
Contact e-mail or additional email address
phone: string (optional) Example: 83214567788
Contact phone or mobile phone
search_string: string (optional) Example: desk
Target substring

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 3020,
  "name": "Housecoat Sally",
  "last_name": "Housecoat",
  "first_name": "Sally",
  "patronymic": null,
  "position": "Manager",
  "email": "employee@okdesk.com",
  "phone": "+79459999999",
  "mobile_phone": "+79999999999",
  "comment": "Senior Manager is responsible for Strategic Planning",
  "cc_email": "employee@okdesk.com",
  "telegram_username": "egorov",
  "active": true,
  "login": "egorov3020",
  "crm_1c_id": "67067c3349a8",
  "updated_at": "2019-09-30T15:12:09.095+03:00",
  "company_id": 1,
  "company_name": "Company name",
  "additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
  "access_level": [
    "company_issues"
  ],
  "maintenance_entity_ids": [
    12
  ],
  "authentication_code": "6920-6310-7466-4123",
  "observers": [
    {
      "id": 2,
      "name": "Fred Bloggs"
    },
    {
      "id": 1,
      "name": "John Smith"
    }
  ],
  "default_assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "parameters": [
    {
      "code": "attr1",
      "name": "Contact number",
      "field_type": "ftstring",
      "value": "2368590"
    }
  ],
  "observable_companies": [
    {
      "id": 1040,
      "name": "Okdesk"
    },
    {
      "id": 1041,
      "name": "Acme Ltd."
    }
  ],
  "last_seen": "2019-09-30T15:12:09.095+03:00"
}

Creating a contact

POST`/api/v1/contacts/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
first_name	string	required	Name
last_name	string	required	Last name
patronymic	string	optional	Middle name
telegram_username	string	optional	Contact’s Telegram account
position	string	optional	Title
login	string	optional	Contact login
password	string	optional	Contact password
email	string	optional	Contact e-mail address
additional_emails	string	optional	Additional emails
phone	string	optional	Phone number
mobile_phone	string	optional	Mobile phone number
comment	string	optional	Additional information on the contact
company_id	string	optional	ID of the company to which the contact is referenced (contact without reference to any company is allowed)
observer_ids	array of string	optional	Array of ID of users who are contact’s viewers
default_assignee_id	string	optional	The ID of agent assigned responsible for this contact by default
access_level	array of string	optional	The level of access to the contact’s profile. May include the following values: company_issues (view company’s tickets), maintenance_entities_issues (show tickets referenced to service aims), observable_companies_issues (show monitored company’s tickets), access_to_reports_for_company (access to your company’s reports), access_to_reports_for_external_companies (access to reports on monitored companies), allow_close_company_issues (allow closing all company tickets), allow_close_observable_companies_issues (allow closing monitored companies tickets), allow_close_maintenance_entity_issues (allow closing tickets related to assigned service aims), allow_viewing_issue_services (allow viewing ticket quantities), allow_editing_issue_services (allow editing ticket quantities), allow_viewing_issue_sidebar_time_entries (allow viewing the breakdown of the time spent on the ticket), allow_issue_confirmation (allow ticket approval)
cc_email	string	optional	Email for CC
maintenance_entity_ids	array of integer	optional	Array of service aim IDs
observable_company_ids	array of integer	optional	Array of viewed company IDs
crm_1c_id	string	optional	Object ID in 1C, required to integrate with 1C; is not displayed in the web interface
custom_parameters	associative array	optional	Contact extended attributes

Please note

Contact will not be created, if the service aim IDs (maintenance_entity_ids) do not correspond to the company’s ID (company_id).
The last_seen parameter has a 5-minute accuracy.

Restriction of access rights

Creation of a contact person is available for agents in accordance with the settings of access rights. You can specify a login, password, as well as the level of access to your personal account only if the key-linked agent has the rights to edit the contact’s access details. It is only possible to specify a link with a company and companies being monitored when creating a contact if the key-linked agent has the right to add contact persons to the company in accordance with the access rights settings. Specifying a link to service aims when creating a contact will be possible only if the key-linked agent has the right to add contact persons to the service aim in accordance with the settings of access rights. Only contacts with the reference to the corresponding company can be created for the keys associated with contacts. Transferred values of “Responsible manager” and “Viewers by default” parameters will be ignored for the keys associated with contacts. The authentication_code, login and access_level parameters are available only to agents with the right to view contact’s access details. The last_seen parameter is available only for agents with the Administrator role.

URI example

POST https://<account>.okdesk.com/api/v1/contacts/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "contact": {
    "first_name": "Joe",
    "last_name": "Meatball",
    "patronymic": "Smith",
    "telegram_username": "joe",
    "position": "Manager",
    "login": "employee@okdesk.com",
    "password": "strong_password",
    "email": "employee@okdesk.com",
    "additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
    "phone": "+79459999999",
    "mobile_phone": "+79999999999",
    "comment": "Senior Manager is responsible for Strategic Planning",
    "company_id": "1",
    "observer_ids": [
      "1",
      "2"
    ],
    "default_assignee_id": "1",
    "cc_email": "egorov@okdesk.com",
    "crm_1c_id": "67067c3a29a8",
    "access_level": [
      "access_to_reports_for_company"
    ],
    "maintenance_entity_ids": [
      15
    ],
    "observable_company_ids": [
      1040,
      1041
    ],
    "custom_parameters": {
      "code2": "2019-02-15"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 3020,
  "name": "Joe Meatball Smith",
  "last_name": "Joe",
  "first_name": "Meatball",
  "patronymic": "Smith",
  "telegram_username": "joe",
  "position": "Manager",
  "email": "employee@okdesk.com",
  "phone": "+79459999999",
  "mobile_phone": "+79999999999",
  "comment": "Senior Manager is responsible for Strategic Planning",
  "company_id": 1,
  "company_name": "Company name",
  "additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
  "cc_email": "egorov@okdesk.com",
  "crm_1c_id": "67067c3a29a8",
  "updated_at": "2019-09-30T17:30:08.288+03:00",
  "active": true,
  "observers": [
    {
      "id": 2,
      "name": "Fred Bloggs"
    },
    {
      "id": 1,
      "name": "John Smith"
    }
  ],
  "access_level": [
    "access_to_reports_for_company"
  ],
  "maintenance_entity_ids": [
    15
  ],
  "default_assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "authentication_code": "6920-6310-7466-4123",
  "parameters": [
    {
      "code": "code2",
      "name": "Date",
      "field_type": "ftdate",
      "value": "2019-02-15"
    }
  ],
  "observable_companies": [
    {
      "id": 1040,
      "name": "Okdesk"
    },
    {
      "id": 1041,
      "name": "Acme Ltd."
    }
  ],
  "last_seen": "2019-09-30T15:12:09.095+03:00"
}

Editing a contact

PATCH`/api/v1/contacts/{contact_id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
first_name	string	optional	Name
last_name	string	optional	Last name
patronymic	string	optional	Middle name
telegram_username	string	optional	Contact’s Telegram account
position	string	optional	Title
email	string	optional	Contact e-mail address
additional_emails	string	optional	Additional emails
login	string	optional	Contact login
password	string	optional	Contact password
phone	string	optional	Phone number
mobile_phone	string	optional	Mobile phone number
company_id	string	optional	ID of the company to which the contact is referenced (contact without reference to any company is allowed)
access_level	array of string	optional	The level of access to the contact’s profile. May include the following values: company_issues (view company’s tickets), maintenance_entities_issues (show tickets referenced to service aims), observable_companies_issues (show monitored company’s tickets), access_to_reports_for_company (access to your company’s reports), access_to_reports_for_external_companies (access to reports on monitored companies), allow_close_company_issues (allow closing all company tickets), allow_close_observable_companies_issues (allow closing monitored companies tickets), allow_close_maintenance_entity_issues (allow closing tickets related to assigned service aims), allow_viewing_issue_services (allow viewing ticket quantities), allow_editing_issue_services (allow editing ticket quantities), allow_viewing_issue_sidebar_time_entries (allow viewing the breakdown of the time spent on the ticket), allow_issue_confirmation (allow ticket approval)
cc_email	string	optional	Email for CC
maintenance_entity_ids	array of integer	optional	Array of service aim IDs
observable_company_ids	array of integer	optional	Array of viewed company IDs
crm_1c_id	string	optional	Object ID in 1C, required to integrate with 1C; is not displayed in the web interface
custom_parameters	associative array	optional	Contact extended attributes

Please note

The contact will not be modified, if the service aim IDs (maintenance_entity_ids) do not correspond to the transferred company ID (company_id).
If the company’s ID (company_id) has not been transferred in the course of contact editing, then the service aim’s correspondence will be checked for the contact’s current company.
The last_seen parameter has a 5-minute accuracy.

Restriction of access rights

Editing of the contact will be completed only if the key-linked agent has the rights to view the contact’s card and edit the contact’s attributes in accordance with the access rights settings. The authentication_code, login and access_level parameters are available only to agents with the right to view contact’s access details. The last_seen parameter is available only for agents with the Administrator role. It is only possible to specify a link with a company and companies being monitored if the key-linked agent has the right to add contact persons to the company in accordance with the access rights settings. Specifying a link to service aims will be possible only if the key-linked agent has the right for adding contact persons to the service aim in accordance with the settings of access rights.

URI example

PATCH https://<account>.okdesk.com/api/v1/contacts/10?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
contact_id: integer (required) Example: 10
Contact ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "contact": {
    "first_name": "John",
    "last_name": "Doe",
    "patronymic": "Smith",
    "telegram_username": "john",
    "position": "Manager",
    "login": "ivanov",
    "password": "strong_password",
    "email": "ivanov@okdesk.com",
    "additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
    "phone": "+79452222222",
    "mobile_phone": "+73333333333",
    "company_id": "33",
    "cc_email": "ivanov@okdesk.com",
    "crm_1c_id": "67067c3a29a8",
    "access_level": [
      "company_issues"
    ],
    "maintenance_entity_ids": [
      12
    ],
    "observable_company_ids": [
      1040,
      1041
    ],
    "custom_parameters": {
      "code2": "2019-02-15"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "sequential_id": 10,
  "name": "Doe John Smith",
  "first_name": "John",
  "last_name": "Doe",
  "patronymic": "Smith",
  "telegram_username": "john",
  "position": "Manager",
  "email": "ivanov@okdesk.com",
  "login": "ivanov",
  "phone": "+79452222222",
  "mobile_phone": "+73333333333",
  "company_id": 33,
  "company_name": "Company name",
  "additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
  "cc_email": "ivanov@okdesk.com",
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "updated_at": "2019-09-30T15:12:09.095+03:00",
  "access_level": [
    "company_issues"
  ],
  "authentication_code": "6920-6310-7466-4123",
  "parameters": [
    {
      "code": "code2",
      "name": "Date",
      "field_type": "ftdate",
      "value": "2019-02-15"
    }
  ],
  "observable_companies": [
    {
      "id": 1040,
      "name": "Okdesk"
    },
    {
      "id": 1041,
      "name": "Acme Ltd."
    }
  ],
  "last_seen": "2019-09-30T15:12:09.095+03:00"
}

Archiving contacts

PATCH`/api/v1/contacts/{id}/activations{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
active	boolean	required	Contact activation status

Restriction of access rights

Contact archiving is available to agents in accordance with the settings of access rights.

URI example

PATCH https://<account>.okdesk.com/api/v1/contacts/1/activations?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 1
contact ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "sequential_id": 10,
  "name": "Doe John Smith",
  "first_name": "John",
  "last_name": "Doe",
  "patronymic": "Smith",
  "position": "Manager",
  "email": "ivanov@okdesk.com",
  "login": "ivanov",
  "phone": "+79452222222",
  "mobile_phone": "+73333333333",
  "company_id": 33,
  "company_name": "Company name",
  "additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
  "cc_email": "ivanov@okdesk.com",
  "crm_1c_id": "67067c3a29a8",
  "updated_at": "2019-09-30T15:12:09.095+03:00",
  "active": true,
  "access_level": [
    "company_issues"
  ],
  "authentication_code": "6920-6310-7466-4123",
  "parameters": [
    {
      "code": "code2",
      "name": "Date",
      "field_type": "ftdate",
      "value": "2019-02-15"
    }
  ],
  "observable_companies": [
    {
      "id": 1040,
      "name": "Okdesk"
    },
    {
      "id": 1041,
      "name": "Acme Ltd."
    }
  ],
  "last_seen": "2019-09-30T15:12:09.095+03:00"
}

Obtaining list by parameters

GET`/api/v1/contacts/list{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
company_ids	array of integer	optional	Array of company IDs (set the value “0” to the parameter to show contacts without a company). Example: company_ids[]=1
default_assignee_ids	array of integer	optional	Array of IDs of agents who are responsible for the contacts (set the value “0” to the parameter to show contacts without a responsible agent). Example: default_assignee_ids[]=1
default_assignee_group_ids	array of integer	optional	Array of contact responsible group IDs (set the value “0” to the parameter to show contacts without a responsible group). Example: default_assignee_group_ids[]=1
observer_ids	array of integer	optional	Array of IDs of agents who are viewers for the contacts (set the value “0” to the parameter to show contacts without a viewer). Example: observer_ids[]=1
observer_group_ids	array of integer	optional	Array of contact viewer group IDs (set the value “0” to the parameter to show contacts without viewer groups). Example: observer_group_ids[]=1
active	string	optional	Activity status. Takes true or false value
created_since	string	optional	The date the contact was created in the account’s time zone (From) Example: created_since=2019-05-25
created_until	string	optional	The date the contact was created in the account’s time zone (Until) Example: created_until=2019-05-25
updated_since	string	optional	The date the contact was modified in the account’s time zone (From) Example: updated_since=2019-05-25
updated_until	string	optional	The date the contact was modified in the account’s time zone (Until) Example: updated_until=2019-05-25
custom_parameters	associative array	optional	Associative array of Extended attribute code pairs: Value or set of values
page	associative array	optional	Associative array of parameters for a per-page display of the contact list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the contact starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the contact id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the contact’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the contact’s lowest id. Example: page[direction]=forward

Restriction of access rights

Retrieving of the contacts list will be completed only if the key-linked agent has access to the contacts list in accordance with the access rights settings. The last_seen parameter is available only for agents with the Administrator role.

Please note

This method returns no more than 100 entries.
If the parameters of per-page display are not transferred, the list of the last 100 contacts created will be returned.
The last_seen parameter has a 5-minute accuracy.

Valid values of extended attributes:

Parameter type	Type	Description
Date	string	There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12
Date/time	string	There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12
Checkbox	string	Two values – true and false – are available. Example: custom_parameters[checkbox_code]=true
List item	array of string	An array of list values. Example: custom_parameters[list_code][]=list_value
List item set	array of string	An array of list values. Example: custom_parameters[list_code][]=list_value

An example of a query with the contact list per-page display parameters:

https://<account>.okdesk.com/api/v1/contacts/list?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/contacts/list?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 9,
    "name": "Doe John Smith",
    "first_name": "John",
    "last_name": "Doe",
    "patronymic": "Smith",
    "position": "Manager",
    "active": true,
    "email": "mail@johndoe.com",
    "phone": "+79876543210",
    "mobile_phone": "+71234567890",
    "updated_at": "2019-09-30T15:12:09.095+03:00",
    "company_id": 2,
    "company_name": "Company name",
    "additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
    "last_seen": "2019-09-30T15:12:09.095+03:00",
    "parameters": [
      {
        "code": "attr1",
        "name": "Contact number",
        "field_type": "ftstring",
        "value": "2368590"
      }
    ]
  },
  {
    "id": 8,
    "name": "Castle Frank Rook",
    "first_name": "Frank",
    "last_name": "Castle",
    "patronymic": "Rook",
    "position": "Expert",
    "active": true,
    "email": "mail@frankcastle.com",
    "phone": "+79876543211",
    "mobile_phone": "+71234567899",
    "updated_at": "2019-09-30T15:12:09.095+03:00",
    "company_id": 2,
    "company_name": "Company name",
    "additional_emails": "contact@okdesk.ru, contact2@okdesk.ru",
    "last_seen": "2019-09-30T15:12:09.095+03:00",
    "parameters": [
      {
        "code": "attr1",
        "name": "Contact number",
        "field_type": "ftstring",
        "value": "2368591"
      }
    ]
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "created_until": [
      "Invalid date"
    ],
    "observer_ids": {
      "1": [
        "must be an integer"
      ]
    },
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Contracts ¶

Contract search

GET`/api/v1/agreements/{?api_token,search_string}`

The search is carried out by entering the substring that is a part of the contract name, value of crm_1c_id parameter, or a String-type extended attribute of the contract.

Restriction of access rights

Contract search will be performed only if a key-related agent has access to the list of contract in accordance with the settings of access rights.

URI example

GET https://<account>.okdesk.com/api/v1/agreements/?api_token=3e9a214215f493c4&search_string=desk

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
search_string: string (required) Example: desk
Target substring

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "title": "Service contract No.2016-03/1",
    "start_date": "23-04-2018",
    "end_date": "24-04-2018",
    "cost": 322,
    "crm_1c_id": "desktop_1",
    "active": false,
    "company_ids": [
      1
    ],
    "default_assignee": {
      "employee": {
        "id": 1,
        "name": "John Smith"
      },
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    },
    "observers": {
      "employees": [
        {
          "id": 2,
          "name": "Fred Bloggs"
        },
        {
          "id": 1,
          "name": "John Smith"
        }
      ],
      "groups": [
        {
          "id": 5,
          "name": "Quality control"
        }
      ]
    },
    "service_periods": [
      {
        "id": 1,
        "agreement_id": 1,
        "start_date": "23-04-2018",
        "end_date": "24-04-2018",
        "cost": 322,
        "comment": "Comment",
        "reminder_date": "24-04-2018",
        "postpay": false,
        "paid": true
      }
    ],
    "parameters": [
      {
        "code": "attr1",
        "name": "Document No.",
        "field_type": "ftstring",
        "value": "2368590"
      }
    ]
  }
]

Contract info

GET`/api/v1/agreements/{id}{?api_token}`

Restriction of access rights

Contract info will be provided only if the key-linked agent has the right to view the сontract in accordance with the settings of access rights.

URI example

GET https://<account>.okdesk.com/api/v1/agreements/1?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 1
Contract ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "title": "Service contract No.2016-03/1",
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "company_ids": [
    1
  ],
  "default_assignee": {
    "employee": {
      "id": 1,
      "name": "John Smith"
    },
    "group": {
      "id": 1,
      "name": "Targeting"
    }
  },
  "observers": {
    "employees": [
      {
        "id": 2,
        "name": "Fred Bloggs"
      },
      {
        "id": 1,
        "name": "John Smith"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "Quality control"
      }
    ]
  },
  "billing_status": "active_now",
  "service_periods": [
    {
      "id": 1,
      "agreement_id": 1,
      "start_date": "23-04-2018",
      "end_date": "24-04-2018",
      "cost": 322,
      "comment": "Comment",
      "reminder_date": "24-04-2018",
      "postpay": false,
      "paid": true
    }
  ],
  "parameters": [
    {
      "code": "attr1",
      "name": "Document No.",
      "field_type": "ftstring",
      "value": "2368590"
    }
  ]
}

Editing the contract

PATCH`/api/v1/agreements/{id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
title	string	optional	Contract name
crm_1c_id	string	optional	Object ID in 1C, required to integrate with 1C; is not displayed in the web interface
active	boolean	optional	Contract activation status
default_assignee_id	integer	optional	ID of responsible agent by default
default_assignee_group_id	integer	optional	ID of responsible group by default
observer_ids	array of int	optional	Array of IDs of users viewing the contract
observer_group_ids	array of int	optional	Array of IDs of agent groups viewing the contract
company_ids	array	optional	Array of company IDs. To remove companies from the contract, you need to transfer the value []
custom_parameters	associative array	optional	Contract extended attributes

Restriction of access rights

Editing of the contract will be completed only if the key-linked agent has the rights to view the contract, close the contract, editing the contract binding to the company and edit the contract attributes in accordance with the access rights settings. This method is not available for contact-associated keys.

URI example

PATCH https://<account>.okdesk.com/api/v1/agreements/1?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 1
Contract ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "agreement": {
    "title": "Service contract No.2016-03/1",
    "crm_1c_id": "67067c3a29a8",
    "active": false,
    "company_ids": [
      1,
      2
    ],
    "observer_ids": [
      1,
      2
    ],
    "custom_parameters": {
      "code2": "2019-02-15"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "title": "Service contract No.2016-03/1",
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "crm_1c_id": "67067c3a29a8",
  "active": false,
  "company_ids": [
    1,
    2
  ],
  "default_assignee": {
    "employee": {
      "id": 1,
      "name": "John Smith"
    },
    "group": {
      "id": 1,
      "name": "Targeting"
    }
  },
  "observers": {
    "employees": [
      {
        "id": 2,
        "name": "Fred Bloggs"
      },
      {
        "id": 1,
        "name": "John Smith"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "Quality control"
      }
    ]
  },
  "service_periods": [
    {
      "id": 1,
      "agreement_id": 1,
      "start_date": "23-04-2018",
      "end_date": "24-04-2018",
      "cost": 322,
      "comment": "Comment",
      "reminder_date": "24-04-2018",
      "postpay": false,
      "paid": true
    }
  ],
  "parameters": [
    {
      "code": "code2",
      "name": "Contract date",
      "field_type": "ftdate",
      "value": "2019-02-15"
    }
  ]
}

Creating a contract

POST`/api/v1/companies/{company_id}/agreements{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
title	string	required	Contract name
crm_1c_id	string	optional	Object ID in 1C, required to integrate with 1C; is not displayed in the web interface
default_assignee_id	integer	optional	ID of responsible agent by default
default_assignee_group_id	integer	optional	ID of responsible group by default
observer_ids	array of int	optional	Array of IDs of users viewing the contract
observer_group_ids	array of int	optional	Array of IDs of agent groups viewing the contract
custom_parameters	associative array	optional	Contract extended attributes

Restriction of access rights

Creating a contract is possible only if the agent associated with the key has the right to create an contract and to add an contract to the company. This method is not available for contact-associated keys.

URI example

POST https://<account>.okdesk.com/api/v1/companies/1/agreements?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
company_id: integer (required) Example: 1
Company ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "agreement": {
    "title": "Service contract No.2016-03/1",
    "crm_1c_id": "67067c3a29a8",
    "custom_parameters": {
      "code2": "2019-02-12"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "title": "Service contract No.2016-03/1",
  "start_date": null,
  "end_date": null,
  "cost": 0,
  "crm_1c_id": "67067c3a29a8",
  "active": true,
  "company_ids": [
    1
  ],
  "default_assignee": {
    "employee": {
      "id": 1,
      "name": "John Smith"
    },
    "group": {
      "id": 1,
      "name": "Targeting"
    }
  },
  "observers": {
    "employees": [
      {
        "id": 2,
        "name": "Fred Bloggs"
      },
      {
        "id": 1,
        "name": "John Smith"
      }
    ],
    "groups": [
      {
        "id": 5,
        "name": "Quality control"
      }
    ]
  },
  "service_periods": [],
  "parameters": [
    {
      "code": "code2",
      "name": "Contract date",
      "field_type": "ftdate",
      "value": "2019-02-12"
    }
  ]
}

Obtaining a list of company contracts

GET`/api/v1/companies/{company_id}/agreements{?api_token}`

Please note

This method returns list of contracts IDs associated with the assigned company.

Restriction of access rights

The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”.

URI example

GET https://<account>.okdesk.com/api/v1/companies/1/agreements?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
company_id: integer (required) Example: 1
Company ID.

Response 200

HideShow

Adding service term

POST`/api/v1/agreements/{agreement_id}/service_periods{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
start_date	string	required	Start date Example: start_date=23-04-2018
end_date	string	required	End date Example: end_date=24-04-2018
cost	float	optional	Cost
comment	string	optional	Comment
reminder_date	string	optional	End date reminder Example: reminder_date=24-04-2018
postpay	boolean	optional	Postpaid service indicator
paid	boolean	optional	Payment indicator

Restriction of access rights

Adding service term will be completed only if the key-linked agent has the rights to view the contract and add the contract service periods in accordance with the access rights settings. This method is not available for contact-associated keys.

URI example

POST https://<account>.okdesk.com/api/v1/agreements/1/service_periods?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
agreement_id: integer (required) Example: 1
Contract ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "service_period": {
    "start_date": "23-04-2018",
    "end_date": "24-04-2018",
    "cost": 322,
    "comment": "Comment",
    "reminder_date": "24-04-2018",
    "postpay": false,
    "paid": true
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "agreement_id": 1,
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "comment": "Comment",
  "reminder_date": "24-04-2018",
  "postpay": false,
  "paid": true
}

Changing the service term

PATCH`/api/v1/agreements/{agreement_id}/service_periods/{id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
start_date	string	optional	Start date Example: start_date=23-04-2018
end_date	string	optional	End date Example: end_date=24-04-2018
cost	float	optional	Cost
comment	string	optional	Comment
reminder_date	string	optional	End date reminder Example: reminder_date=24-04-2018
postpay	boolean	optional	Postpaid service indicator
paid	boolean	optional	Payment indicator

Restriction of access rights

Changing the service term will be completed only if the key-linked agent has the rights to view the contract and edit the contract service periods in accordance with the access rights settings. This method is not available for contact-associated keys.

URI example

PATCH https://<account>.okdesk.com/api/v1/agreements/1/service_periods/1?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
agreement_id: integer (required) Example: 1
Contract ID.
id: integer (required) Example: 1
Service term ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "service_period": {
    "start_date": "23-04-2018",
    "end_date": "24-04-2018",
    "cost": 322,
    "comment": "Comment",
    "reminder_date": "24-04-2018",
    "postpay": false,
    "paid": true
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "agreement_id": 1,
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "comment": "Comment",
  "reminder_date": "24-04-2018",
  "postpay": false,
  "paid": true
}

Removing the service term

DELETE`/api/v1/agreements/{agreement_id}/service_periods/{id}{?api_token}`

Restriction of access rights

Removing the service term will be completed only if the key-linked agent has the rights to view the card of contract and removing the contract service periods in accordance with the access rights settings. This method is not available for contact-associated keys.

URI example

DELETE https://<account>.okdesk.com/api/v1/agreements/1/service_periods/1?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
agreement_id: integer (required) Example: 1
Contract ID.
id: integer (required) Example: 1
Service term ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "agreement_id": 1,
  "start_date": "23-04-2018",
  "end_date": "24-04-2018",
  "cost": 322,
  "comment": "Comment",
  "reminder_date": "24-04-2018",
  "postpay": false,
  "paid": true
}

Tickets ¶

Ticket creation

POST`/api/v1/issues/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
title	string	required	Subject
description	string	optional	Description
company_id	string	optional	The ID of the company linked to the ticket
contact_id	string	optional	The ID of the contact linked to the ticket
agreement_id	string	optional	The ID of the contract linked to the ticket
assignee_id	string	optional	Responsible agent ID
group_id	string	optional	Agent’s responsible group ID
observer_ids	array of integer	optional	Array of IDs of agents viewing the ticket
observer_group_ids	array of integer	optional	Array of IDs of agent groups viewing the ticket
contact_observer_ids	array of integer	optional	Array of IDs of contacts viewing the ticket
maintenance_entity_id	string	optional	The ID of the service aim linked to the ticket
equipment_ids	array	optional	Array of IDs of equipment linked to the ticket
type	string	optional	Ticket type code
priority	string	optional	Ticket priority code
deadline_at	string	optional	Planned resolution date
start_execution_until	string	optional	Scheduled for (date/time)
planned_execution_in_minutes	number	optional	Planned execution (in minutes)
custom_parameters	associative array	optional	Ticket extended attributes
parent_id	string	optional	Parent ticket ID
author	associative array	optional	Ticket’s author. To specify the author, you need to pass 2 parameters: id (author’s ID, string, required) and type (author’s type, string, required, valid values: employee and contact). The method is only available for keys associated with the user roles “Administrator”.

Please note

If type or priority parameters are empty, the ticket will be created with priority and type set “by default” in account settings.

Restriction of access rights

start_execution_until and start_execution_until parameters are available for the keys associated with agents.

For the keys associated with agents, creating a ticket and adding a “Planned resolution date” field are available in accordance with access rights settings. It is only possible to specify a company when creating a ticket if the key-linked agent has the right to create a ticket by company in accordance with the access rights settings. It is only possible to specify a contact when creating a ticket if the key-linked agent has the right to create a ticket for a transferred contact in accordance with the access rights settings. It is allowed to specify equipment while creating a ticket only if a key-related agent is entitled to create tickets on equipment in accordance with the settings of access rights. Specifying a service aim will be possible only if the key-related agent has the right for creation of a ticket for the service aim in accordance with the settings of access rights. Specifying an contract is possible only if the agent associated with the key has the right to create an tickets for the contract in accordance with the access rights settings.

For the keys associated with contacts, the “Responsible agent” (will be determined automatically by the rules in the account), “Viewers“ (will be determined automatically according to the rules set in the account) and “Company” (the company associated with the company will be automatically set up with the contact person) parameters will be ignored when creating a ticket. “Contact”, “Contract”, “Related equipment”, and “Service aim” parameters will be checked for the matching of the transferred values with the company’s contact.

Acceptable parameters of attachable files:

Name	Type	Mandatory	Description
attachment	string	required	Attachable file
is_public	string	optional	File availability
description	string	optional	File description

Please note

The content of the query with attached files shall be multipart/form-data and contain the corresponding title.

URI example

POST https://<account>.okdesk.com/api/v1/issues/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "issue": {
    "title": "The laptop doesn't work",
    "description": "Laptop failed to boot; please check it out",
    "company_id": "33",
    "contact_id": "4",
    "agreement_id": "12",
    "type": "service",
    "priority": "high",
    "maintenance_entity_id": "15",
    "equipment_ids": [
      "6",
      "8"
    ],
    "deadline_at": "2018-05-09 09:15",
    "custom_parameters": {
      "address": "42 Prestwick Road",
      "checked": true
    },
    "parent_id": "102",
    "author": {
      "id": "1",
      "type": "contact"
    },
    "observer_ids": [
      2,
      5,
      7
    ],
    "observer_group_ids": [
      4,
      10
    ],
    "contact_observer_ids": [
      56,
      86
    ]
  }
}

Request with attached files

HideShow

Headers

Content-Type: multipart/form-data

Body

curl  -H "Content-Type: multipart/form-data" -F "issue[title]=The laptop doesn't work" -F "issue[priority]=high"
-F "issue[observer_ids][]=2" -F "issue[observer_ids][]=5" -F "issue[observer_group_ids][]=1"
-F "issue[attachments][0][attachment]=@/home/user/file.jpg" -F "issue[attachments][0][is_public]=true"
-F "issue[attachments][0][description]=Warranty terms"
-F "issue[attachments][1][attachment]=@/home/user/file.docx" -F "issue[attachments][1][is_public]=false"
https://<account>.okdesk.com/api/v1/issues/{?api_token}

where @/home/user/file.jpg is a path to the local file
for windows path will be like @"C:/myfile.txt"

Response 200

HideShow

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
    "issue": {
        "title": "Broken socket",
        "company_id": "-5",
        "type": "unknown",
        "priority": 'high',
        "custom_parameters": {
            "total": "4"
        },
        "parent_id": "102"
    }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "company_id": "Entry -5 does not exist",
    "type": "Entry unknown does not exist",
    "custom_parameters_total": "the extended parameter total does not exist"
  }
}

Change of responsible agent

PATCH`/api/v1/issues/{issue_id}/assignees{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
assignee_id	string	optional	Responsible agent ID
group_id	string	optional	Responsible group ID

Please note

One of the parameters (assignee_id, group_id) must be set

Restriction of access rights

The change of responsibility for the ticket will be performed only if the user associated with the key has the right to view the ticket and to change the responsible agent in accordance with the access rights settings. This method is not available for keys associated with contacts.

URI example

PATCH https://<account>.okdesk.com/api/v1/issues/763/assignees?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
ticket ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Changing the planned date of ticket resolution

PATCH`/api/v1/issues/{issue_id}/deadlines{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
deadline_at	string	required	Planned resolution date

Restriction of access rights

The planned date of ticket resolution will be changed only if the user associated with the key has the right to view the ticket and to change the planned resolution date for this ticket. This method is not available for keys associated with contacts.

URI example

PATCH https://<account>.okdesk.com/api/v1/issues/763/deadlines?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
ticket ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Request with incorrect date

HideShow

Response 422

HideShow

Response 422

HideShow

Change the “Delayed until” date of ticket

PATCH`/api/v1/issues/{issue_id}/delays{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
delay_to	string	required	The time to which the application is postponed.

Restriction of access rights

The “Delayed until” date of ticket will be changed only if a key-related user has rights to view the ticket and change the “Delayed until” date, and if the ticket is in delayed status. This method is not available for keys associated with contacts.

URI example

PATCH https://<account>.okdesk.com/api/v1/issues/763/delays?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
ticket ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": "2019-09-24T14:35:00.000+03:00",
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Request with incorrect date

HideShow

Response 422

HideShow

Response 422

HideShow

Request with non-delayed status

HideShow

Response 422

HideShow

Change type of ticket

PATCH`/api/v1/issues/{issue_id}/types{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
code	string	required	ticket type code

Restriction of access rights

This method is only available for keys associated with agents who have access to actions “View the ticket”, “Ticket type change” (including the right to set the transferred type according to the setting “Except for setting of a ticket type”).
This method is not available for contact-associated keys.

URI example

PATCH https://<account>.okdesk.com/api/v1/issues/763/types?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
ticket ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Change the link of the ticket to the client contract service aim or equipment

PATCH`/api/v1/issues/{issue_id}/related_attributes{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
company_id	integer	optional	Company ID
contact_id	integer	optional	Contact ID
agreement_id	integer	optional	Contract ID
maintenance_entity_id	integer	optional	Service aim ID
equipment_ids	array of integer	optional	Array of equipment ID

Restriction of access rights

This method is only available for keys associated with agents who have access to actions “View the ticket”, “Change the link of the ticket to the client, contract, service aim, or equipment”.
This method is not available for contact-associated keys.

URI example

PATCH https://<account>.okdesk.com/api/v1/issues/763/related_attributes?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
ticket ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 1,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [
    1
  ],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 1,
    "name": "Sally Housecoat"
  },
  "agreement": {
    "id": 1,
    "title": "Service contract"
  },
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Editing extended ticket attributes

POST`/api/v1/issues/{issue_id}/parameters{?api_token}`

Parameters:

Name	Type	Mandatory	Description
custom_parameters	associative array	required	Ticket extended attributes

Restriction of access rights

Editing of extended attributes will be available if the user with the key assigned is eligible to view the ticket and to edit the particular attribute and extended attributes in general.

Please note

The value of Image-type extended attribute shall be passed as a string in base64 format considering the following limitations:

String size (of an image coded in base64) shall not exceed 1MB
Image format: PNG
Aspect ratio: 1.86:1
String shall start with URL structure data:image/png;base64,

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAjAAAAEsCAYAA...jLNtZ4AAAAASUVORK5CYII=

URI example

POST https://<account>.okdesk.com/api/v1/issues/763/parameters?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
ticket ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "custom_parameters": {
    "address": "Moscow st 2",
    "checked": true,
    "datetime": "2018-05-09 09:15",
    "multiselect": [
      "five"
    ],
    "select": "one",
    "date": "2018-05-09"
  }
}

Response 200

Request with incorrect date

HideShow

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "base": [
      [
        {
          "datetime": "The extended parameter has invalid date/time format Engineer's arrival date and time"
        }
      ]
    ]
  }
}

Request when attribute is required

HideShow

Response 422

HideShow

Ticket address edit

PATCH`/api/v1/issues/{issue_id}/addresses{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
value	string	required	String representation of the ticket address
coordinates	array of float	required	Ticket address coordinates

Please note

If a non-blank value of at least one parameter is transferred (value, coordinates), the second parameter is required and cannot be empty. If empty values are passed for both parameters, the address in the ticket shall be reset.

Restriction of access rights

The change of the ticket address will be performed only if the user associated with the key has the right to view the ticket and to change the address in accordance with the access rights settings. This method is not available for keys associated with contacts.

URI example

PATCH https://<account>.okdesk.com/api/v1/issues/763/addresses?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
ticket ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Request when one of the parameters is empty

HideShow

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "address_with_coordinates": [
      "The address and coordinates shall be both empty (to delete the ticket address) or both filled in (to edit the ticket address)"
    ]
  }
}

Ticket status change

POST`/api/v1/issues/{issue_id}/statuses{?api_token}`

Please note

open, delayed, completed, and closed system statuses are defined for tickets by default.
You can expand the set of statuses and possible transitions between them in the Settings/Tickets/Ticket statuses section of your Okdesk account.

Valid query parameters:

Name	Type	Mandatory	Description
code	string	required	Status code
delay_to	string	optional	The time to which the application is postponed. The field is mandatory for delayed status only. For other statuses, this parameter will be ignored.
comment	string	optional	Comment to the status. For example, the reason for transition to a new status. You can set the bindingness of this parameter in the “Settings/Tickets/Ticket Status” section.
comment_public	boolean	optional	Comment availability flag. Takes true or false value
custom_parameters	associative array	optional	Ticket extended attributes that are available to the user to enter when switching to a new status or leaving the current status.
time_entry	array	optional	Array of time spents on the ticket that will be added upon changing the status.
assignee_id	string	optional	Responsible agent ID
group_id	string	optional	Agent’s responsible group ID
skip_options	array	optional	Array of flags allowing to skip sending notifications (skip_notifications), webhooks (skip_webhooks), automatic actions (skip_triggers)

Please note

The delay_to parameter is mandatory to switch to delayed status
The comment parameter is mandatory for delayed status by default
To change your ticket status in your account settings, the transition from the current status of the ticket to the status transferred in a query must be permitted
Parameter formatted_spent_time should be like 2 h 30 min or 2:30 or 2.5 hours, etc.

Restriction of access rights

For agents, the ticket status will be changed only if the agent associated with the key has the right to view the ticket and to change the ticket status from the current to the target in accordance with the settings of access rights. For contact-associated keys, not all transitions between statuses are available. A contact can switch ticket only from “Resolved” status for the status specified in “Ticket renewal status” parameter or for “Closed” status, if the corresponding setting is made in the “Settings/Client Portal” section of your account.

URI example

POST https://<account>.okdesk.com/api/v1/issues/763/statuses?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
ticket ID.

Request with status completed

HideShow

Headers

Content-Type: application/json

Body

{
  "code": "completed",
  "comment": "Ticket-related works are fully complete",
  "comment_public": true,
  "assignee_id": "1",
  "group_id": "3",
  "custom_parameters": {
    "code1": "123456789",
    "code2": "2019-02-15",
    "code3": true
  },
  "time_entry": [
    {
      "formatted_spent_time": "12h45m",
      "comment": "Adding time spent when the status is changed",
      "custom_parameters": {
        "code1": "123456789",
        "code2": "2019-02-15",
        "code3": true
      }
    },
    {
      "formatted_spent_time": "1h45m",
      "comment": "Adding time spent when the status is changed",
      "custom_parameters": {
        "code1": "123456789",
        "code2": "2019-02-15",
        "code3": true
      }
    }
  ],
  "skip_options": [
    "skip_triggers",
    "skip_notifications",
    "skip_webhooks"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Request with status delayed

HideShow

Headers

Content-Type: application/json

Body

{
  "code": "delayed",
  "delay_to": "2016-05-25 22:15",
  "comment": "We have run out of consumables, we are waiting for the replenishment.",
  "comment_public": true,
  "custom_parameters": {
    "code1": "123456789",
    "code2": "2019-02-15",
    "code3": true
  },
  "time_entry": [
    {
      "formatted_spent_time": "12h45m",
      "comment": "Adding time spent when the status is changed",
      "custom_parameters": {
        "code1": "123456789",
        "code2": "2019-02-15",
        "code3": true
      }
    }
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": null,
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": "2016-05-25T22:15:00.000+03:00",
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Adding a comment

POST`/api/v1/issues/{issue_id}/comments{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
content	string	required	Comment text. The comment text is in html, which means you need to use html tags to format it. For example, to break lines, use the <br /> tag
author_id	integer	required	ID of user who is the author of the commentary
author_type	string	optional	Type of user who is the author of the commentary Acceptable types: employee (default) - agent, contact - contact person
public	boolean	optional	Comment availability flag. Takes true or false value
attachments	array	optional	List of attached files

Please note

If the public parameter is not specified, the comment created by default will be private.
Contacts cannot create private comments.
If the author_type parameter is not specified, the agent will be author of the comment by default.

Restriction of access rights

For agents, comment will be added to a ticket if only the agent associated with the key has the right to view the ticket and to add the comment in accordance with access rights settings. For contact-associated keys, it is only possible to add a public comment. For keys of users not associated with the “Administrator” role (including contacts), the value of the author_id parameter will be ignored (comment will be added on behalf of the key owner).

Acceptable parameters of attachable files:

Name	Type	Mandatory	Description
attachment	string	required	Attachable file
description	string	optional	File description

Please note

The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
The availability flag for the attachable files will be set similar to the transferred value for the comment, to which the files are attached

URI example

POST https://<account>.okdesk.com/api/v1/issues/254/comments?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 254
ticket ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "comment": {
    "content": "Very soon an engineer will come to you to solve the problem.",
    "public": true,
    "author_id": 10,
    "author_type": "employee"
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "content": "Very soon an engineer will come to you to solve the problem.",
    "public": true,
    "attachments": [],
    "author": {
        "id": 10,
        "name": "Juan Perez"
        "type": "employee"
    }
}

Request with attached files

HideShow

Headers

Content-Type: multipart/form-data

Body

curl  -H "Content-Type: multipart/form-data" -F "comment[content]=Here are the long-awaited report files"
-F "comment[public]=true" -F "comment[author_id]=15" -F "comment[author_type]=employee"
-F "comment[attachments][0][attachment]=@/home/user/file.jpg"
-F "comment[attachments][0][description]=report"
-F "comment[attachments][1][attachment]=@/home/user/file.docx"
https://<account>.okdesk.com/api/v1/issues/{issue_id}/comments/{?api_token}

where @/home/user/file.jpg is a path to the local file
for windows path will be like @"C:/myfile.txt"

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "content": "Here are the long-awaited report files",
  "public": true,
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "file.jpg",
      "description": "report",
      "attachment_file_size": 4149,
      "is_public": true,
      "created_at": "2018-12-24T09:28:50.499+03:00"
    },
    {
      "id": 9,
      "attachment_file_name": "file.docx",
      "description": null,
      "attachment_file_size": 1142,
      "is_public": true,
      "created_at": "2018-12-24T09:28:50.499+03:00"
    }
  ],
  "author": {
    "id": 15,
    "name": "David Sarif",
    "type": "employee"
  }
}

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "comment": {
    "content": "Very soon an engineer will come to you to solve the problem.",
    "public": false,
    "author_id": 22221,
    "author_type": "contact"
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "author_presence": [
      "user is not found"
    ],
    "contact_comment_cannot_be_private": [
      "the contact cannot be an author of a private comment"
    ]
  }
}

Obtaining a list of comments

GET`/api/v1/issues/{issue_id}/comments{?api_token}`

Restriction of access rights

The list of comments to the ticket will be provided only if the user associated with the key has rights to view the ticket.
For keys associated with contacts, a list containing public comments only will be returned.

URI example

GET https://<account>.okdesk.com/api/v1/issues/254/comments?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 254
ticket ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "content": "Very soon an engineer will come to you to solve the problem.",
    "public": false,
    "published_at": "2018-12-24T14:38:43.442+03:00",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Photo",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2018-12-24T09:28:50.499+03:00"
      }
    ],
    "author": {
      "id": 15,
      "name": "David Sarif",
      "type": "employee"
    }
  },
  {
    "id": 2,
    "content": "Thank you, look forward to it.",
    "public": true,
    "published_at": "2018-12-24T15:57:43.374+03:00",
    "attachments": [],
    "author": {
      "id": 12,
      "name": "James Jim Miller",
      "type": "contact"
    }
  }
]

Obtaining detailed list by parameters

GET`/api/v1/issues/list{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
company_ids	array of integer	optional	Array of ticket-related company IDs (set the value “0” to the parameter to show tickets without a company). Example: company_ids[]=1&company_ids[]=2
contact_ids	array of integer	optional	Array of ticket-related contact IDs (set the value “0” to the parameter to show tickets without a contact). Example: contact_ids[]=1&contact_ids[]=2
service_object_ids	array of integer	optional	Array of IDs of service aims that are associated with tickets. Example: service_object_ids[]=1
status_codes	array of string	optional	Array of Ticket status codes Example: status_codes[]=opened&status_codes[]=completed
status_codes_not	array of string	optional	Array of Ticket status codes that are forbidden for the ticket Example: status_codes_not[]=opened&status_codes_not[]=completed
priority_codes	array of string	optional	Array of Ticket priority codes Example: priority_codes[]=high&priority_codes[]=low
type_codes	array of string	optional	Array of Ticket type codes Example: type_codes[]=incident
created_since	string	optional	Date of ticket creation (From) Example: created_since=22-03-2022
created_until	string	optional	Date of ticket creation (Until) Example: created_until=22-06-2022
completed_since	string	optional	Date of ticket resolution (From) Example: completed_since=22-03-2022
completed_until	string	optional	Date of ticket resolution (Until) Example: completed_until=22-06-2022
without_answer	boolean	optional	Flag "Tickets without answer". If the field value is true, tickets not responded by agent are fetched, i.e. tickets that have no agent’s public comment after ticket registration or no agent’s public comment after the last client’s comment. If the field value is false, the tickets with the last agent’s public comment will be fetched.

Valid per-page display parameters:

Name	Type	Mandatory	Description
number	integer	optional	Requested page number. Example: page[number]=2
size	integer	optional	Number of returned entries. Cannot exceed 50. Example: page[size]=30

Valid sorting parameters:

Name	Type	Mandatory	Description
field	string	optional	Sorting parameter field. Available values: created_at, updated_at. created_at - by creation date. updated_at - by last update date. By default: created_at. Example: sorting[field]=updated_at
direction	string	optional	Sorting direction. There are two values available: reverse and forward. forward - returns entries from smallest to largest sorting field value reverse - returns entries from largest to smallest sorting field value. By default: reverse. Example: sorting[direction]=forward

Restriction of access rights

This method is available for keys associated with agents in accordance with access rights settings. For keys associated with contacts, only tickets related to the contact’s company (if a contact has “View company’s tickets” access level) and service aims (if a contact person has “Show tickets referenced to service aims” access level) and monitored companies (if a contact person has “Show monitored company’s tickets” access level) and tickets related directly to the contact will be returned.

URI example

GET https://<account>.okdesk.com/api/v1/issues/list?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 153,
    "title": "Service man is required",
    "created_at": "2022-05-18T12:42:58.685+03:00",
    "completed_at": "2022-05-26T11:21:39.942+03:00",
    "deadline_at": "2022-05-24T16:42:59.000+03:00",
    "delay_to": null,
    "status": {
      "code": "delayed",
      "name": "Delayed",
      "color": "#ffc926"
    },
    "type": {
      "code": "service",
      "name": "Service"
    },
    "priority": {
      "code": "low",
      "name": "Low",
      "color": "#8e9eb3"
    },
    "company": {
      "id": 16,
      "name": "Newco"
    },
    "contact": {
      "id": 1,
      "name": "Sally Housecoat"
    },
    "service_object": {
      "id": 52,
      "name": "Sales outlet No.13"
    },
    "agreement": {
      "id": 28,
      "title": "Service contract"
    },
    "equipments": [
      {
        "id": 120,
        "serial_number": "1101040003532",
        "inventory_number": "51BKB835225",
        "equipment_kind": {
          "code": "laptop",
          "name": "Laptop"
        },
        "equipment_manufacturer": {
          "code": "asus",
          "name": "Asus"
        },
        "equipment_model": {
          "code": "x50sm",
          "name": "x50sm"
        }
      }
    ]
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "company_ids": [
      "must be an integer"
    ],
    "sorting": {
      "direction": [
        "must be one of: reverse, forward"
      ]
    }
  }
}

Ticket rating

POST`/api/v1/issues/{issue_id}/rates{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
rate	string	required	Ticket rating Acceptable values: bad, normal, good

Restriction of access rights

Ticket will be rated if only the user associated with the key has the right to view the ticket and to rate it in accordance with the access rights settings (the contact’s right to rate is determined in the subsection “Tickets \ Ticket rating” in your account’s “Settings” section; the agent’s right to rate is determined in the subsection “Access roles and rights” of the “Settings” section).

URI example

POST https://<account>.okdesk.com/api/v1/issues/254/rates?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 254
ticket ID.

Request

HideShow

Response 200

HideShow

Receiving ticket quantities

GET`/api/v1/issues/{issue_id}/services{?api_token}`

Restriction of access rights

This method is only available to agents according to access rights settings. Herewith, the fields “Cost” (total), “VAT” (total_vat), and “Discount” (discount) will be available only if the user has the right to view the cost in the ticket’s quantities.

URI example

GET https://<account>.okdesk.com/api/v1/issues/153/services?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 153
ticket ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "name": "Delivery to the service center",
    "quantity": 1,
    "discount": 2,
    "total": 600,
    "comment": "",
    "total_vat": 343.83,
    "service": {
      "nomenclature_item_id": 1,
      "code": "timerateservice",
      "unit": "field trip",
      "item_type": "service"
    },
    "price_list": {
      "id": 2,
      "name": "Field services"
    },
    "performer": {
      "id": 3,
      "name": "Max Mustermann"
    }
  },
  {
    "id": 2,
    "name": "Pay per time services",
    "quantity": 3,
    "discount": 2,
    "total": 10290,
    "comment": "Different billed pay per hour services",
    "total_vat": 1569.66,
    "service": {
      "nomenclature_item_id": 2,
      "code": "timerateservice",
      "unit": "man-hour",
      "item_type": "service"
    },
    "price_list": {
      "id": 3,
      "name": "Billed services"
    },
    "performer": {
      "id": 1,
      "name": "Jean Dupont"
    }
  }
]

Adding quantities to a ticket

POST`/api/v1/issues/{issue_id}/services{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
service_id	integer	required	ID of the quantities line from the price list
quantity	number	required	Quantity (non-negative number)
performer_id	integer	optional	Responsible agent ID
comment	string	optional	Comment
total	number	optional	Cost (non-negative number)
discount	integer	optional	Discount (integer from 0 to 100)

Please note

Transferred responsible agent (performer_id) must be an active employee.
If the total and discount parameters are transferred simultaneously, they must correspond to each other based on the cost in the corresponding price list line.
The transferred ID* of the quantities line (service_id) must correspond to the active line of the price list.

Restriction of access rights

This method is not available for contact-associated keys.
This method is only available for keys associated with agents who have access to actions “View the ticket”, “View ticket quantities” and “Adding lines in the ticket quantities”.
If the user does not have the right to view the cost in the ticket quantities, the transferred values of the “total” and “discount” parameters will be ignored.

URI example

POST https://<account>.okdesk.com/api/v1/issues/153/services?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 153
ticket ID.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "name": "Delivery to the service center",
  "quantity": 1,
  "discount": 2,
  "total": 600,
  "comment": "Comment",
  "total_vat": 343.83,
  "service": {
    "nomenclature_item_id": 1,
    "code": "timerateservice",
    "unit": "field trip",
    "item_type": "service"
  },
  "price_list": {
    "id": 2,
    "name": "Field services"
  },
  "performer": {
    "id": 3,
    "name": "Max Mustermann"
  }
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "service_id": [
      "must be an integer"
    ],
    "quantity": [
      "is missing"
    ],
    "performer_id": [
      "The agent does not exist or is not activated"
    ],
    "discount": [
      "must be an integer"
    ],
    "total": [
      "must be greater than or equal to 0"
    ]
  }
}

Obtaining time spent on a ticket

GET`/api/v1/issues/{issue_id}/time_entries{?api_token}`

Restriction of access rights

Information on the time spent on the ticket will be provided only if the user associated with the key has the right to view the ticket and to view the time spent in accordance with the access rights settings. This method is not available for contact-associated keys.

URI example

GET https://<account>.okdesk.com/api/v1/issues/166/time_entries?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 166
ticket ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "spent_time_total": 4,
  "time_entries": [
    {
      "id": 1,
      "comment": "Packaging",
      "spent_time": 1,
      "logged_at": "2018-10-16T11:14:00.000+03:00",
      "employee": {
        "id": 1,
        "login": "andrey@okdesk.com",
        "name": "Jean Dupont"
      },
      "parameters": [
        {
          "code": "address",
          "name": "Call address",
          "field_type": "ftstring",
          "value": "54 Churchill Street"
        }
      ]
    },
    {
      "id": 2,
      "comment": "Shipping",
      "spent_time": 2,
      "logged_at": "2018-10-16T13:10:00.000+03:00",
      "employee": {
        "id": 2,
        "login": "petrov@okdesk.com",
        "name": "Max Mustermann"
      },
      "parameters": [
        {
          "code": "address",
          "name": "Call address",
          "field_type": "ftstring",
          "value": "54 Churchill Street"
        }
      ]
    },
    {
      "id": 3,
      "comment": "Installation",
      "spent_time": 1,
      "logged_at": "2018-10-16T14:10:00.000+03:00",
      "employee": null,
      "parameters": [
        {
          "code": "address",
          "name": "Call address",
          "field_type": "ftstring",
          "value": "54 Churchill Street"
        }
      ]
    }
  ]
}

Deducting time spent on the ticket

POST`/api/v1/issues/{issue_id}/time_entries{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
employee_id	integer	required	Agent ID
formatted_spent_time	string	required	Time consumed(2 h 30 min or 2:30 or 2.5 hours, etc.
logged_at	string	required	Deduction date
comment	string	optional	Comment
custom_parameters	associative array	optional	Associative array of time spent extended attributes

Restriction of access rights

Information on the time spent on the ticket will be provided only if the user associated with the key has the right to view the ticket and to deducting the time spent in accordance with the access rights settings. This method is not available for contact-associated keys.

URI example

POST https://<account>.okdesk.com/api/v1/issues/166/time_entries?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 166
ticket ID.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "time_entries": [
    {
      "employee_id": 1,
      "formatted_spent_time": "60m",
      "logged_at": "2018-10-16 11:14",
      "comment": "Packaging",
      "custom_parameters": {
        "address": "54 Churchill Street"
      }
    },
    {
      "employee_id": 2,
      "formatted_spent_time": "120m",
      "logged_at": "2018-10-16 13:10",
      "comment": "Shipping",
      "custom_parameters": {
        "address": "54 Churchill Street"
      }
    }
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "spent_time_total": 3,
  "time_entries": [
    {
      "id": 1,
      "comment": "Packaging",
      "spent_time": 1,
      "logged_at": "2018-10-16T11:14:00.000+03:00",
      "parameters": [
        {
          "code": "address",
          "name": "Call address",
          "field_type": "ftstring",
          "value": "54 Churchill Street"
        }
      ],
      "employee": {
        "id": 1,
        "login": "andrey@okdesk.com",
        "name": "Jean Dupont"
      }
    },
    {
      "id": 2,
      "comment": "Shipping",
      "spent_time": 2,
      "logged_at": "2018-10-16T13:10:00.000+03:00",
      "parameters": [
        {
          "code": "address",
          "name": "Call address",
          "field_type": "ftstring",
          "value": "54 Churchill Street"
        }
      ],
      "employee": {
        "id": 2,
        "login": "petrov@okdesk.com",
        "name": "Max Mustermann"
      }
    }
  ]
}

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "time_entries": [
    {
      "formatted_spent_time": "60m",
      "comment": "Packaging",
      "custom_parameters": {
        "address": "54 Churchill Street"
      }
    }
  ]
}

Response 422

HideShow

Obtaining a file of a ticket

GET`/api/v1/issues/{issue_id}/attachments/{attachment_id}{?api_token}`

Restriction of access rights

The file information will be provided only if the user associated with the key has rights to view the ticket. For keys associated with contacts, a list containing public files only will be returned.

Please note

File size (attachment_file_size) measured in bytes. Attachment URL is temporary. It expires after 30 seconds of its creation.

URI example

GET https://<account>.okdesk.com/api/v1/issues/166/attachments/22?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 166
ticket ID.
attachment_id: integer (required) Example: 22
File ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 22,
  "attachment_file_name": "image.jpg",
  "description": "",
  "attachment_file_size": 7955,
  "is_public": true,
  "created_at": "2019-10-29T17:31:30.675+03:00",
  "attachment_url": "https://static.okdesk.com/attachments/attachments/000/000/150/original/hqdefault.jpg"
}

Obtaining a checklist of ticket

GET`/api/v1/issues/{issue_id}/check_lists/items{?api_token}`

Restriction of access rights

For contact-associated keys, only available for contacts checklist items will be returned.
This method is only available for keys associated with agents who have access to actions “View the ticket”, “View the checklist in the ticket”.

URI example

GET https://<account>.okdesk.com/api/v1/issues/166/check_lists/items?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 166
ticket ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id": 1001,
        "name": "Check equipment",
        "required": false,
        "visible_for_clients": true,
        "checked_at": "2021-01-27T20:45:00.703+03:00",
        "parameters": [
            {
                "param_type": "text",
                "required": true,
                "value": "No leaks found"
            },
            {
                "param_type": "string",
                "required": true,
                "value": "51BKB835225"
            },
            {
                "param_type": "files",
                "required": false,
                "value": [
                    {
                        "id": 521,
                        "attachment_file_name": "check_photo.jpeg",
                        "attachment_file_size": 3243,
                        "created_at": "2021-04-23T17:20:27.937+03:00"
                    }
                ]
            }
        ],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": 1,
        "position": 1,
        "checked_by_user_id": 2,
        "checked": true
    },
    {
        "id": 1002,
        "name": "Sign a contract",
        "required": true,
        "required_for_transition_to_status_codes": ["completed", "closed"],
        "required_for_transition_from_status_codes": [],
        "visible_for_clients": false,
        "checked_at": null,
        "parameters": [],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": null,
        "position": 2,
        "checked_by_user_id": null,
        "checked": false
    },
]

Ticket checklist creation

POST`/api/v1/issues/{issue_id}/check_lists/items{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	required	Checklist item name.
item_type	string	required	Checklist item type. Can be `point` or `header`.
required_to_status_codes	array of string	optional	An array of status codes with the item execution required when switched thereto. Passed only for mandatory checklist items.
required_from_status_codes	array of string	optional	An array of status codes with the item execution required when switched therefrom. Passed only for mandatory checklist items.
visible_for_clients	boolean	optional	Visibility to client.
planned_execution_in_minutes	number	optional	Planned execution (in minutes)
parameters	associative array	optional	Checklist line parameters. May contain the keys `files` (“Photo” execution parameter), `text` (“Comment” execution parameter) and `string` (“String” execution parameter), which can be either `required` or `unrequired`.
children	array	optional	Nested checklist items. Passed only for the `header` type checklist items.

Restriction of access rights

This method is only available for keys associated with agents who have access to actions “View the ticket”, “Checklist editing in application”.
This method is not available for contact-associated keys.

Restrictions for query parameters

You cannot pass headers at 3 or more nesting levels.
The maximum number of paragraphs and headings that can be created is 200.

URI example

POST https://<account>.okdesk.com/api/v1/issues/166/check_lists/items?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 166
ticket ID.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "check_list": {
    "items": [
      {
        "name": "Check tightness",
        "item_type": "point",
        "visible_for_clients": true,
        "required_to_status_codes": [
          "completed",
          "closed"
        ],
        "required_from_status_codes": [
          "opened"
        ],
        "planned_execution_in_minutes": 60,
        "parameters": {
          "text": "unrequired",
          "files": "required"
        }
      },
      {
        "name": "Documents",
        "item_type": "header",
        "children": [
          {
            "name": "Sign the inspection certificate",
            "item_type": "point",
            "visible_for_clients": true,
            "parameters": {
              "text": "required",
              "string": "required"
            }
          }
        ]
      },
      {
        "name": "Check seal",
        "item_type": "point"
      }
    ]
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 1584,
    "name": "Check tightness",
    "required": true,
    "visible_for_clients": true,
    "checked_at": null,
    "parameters": [
      {
        "param_type": "files",
        "required": true,
        "value": []
      },
      {
        "param_type": "text",
        "required": false,
        "value": null
      }
    ],
    "item_type": "point",
    "parent_id": null,
    "planned_execution_in_hours": 1,
    "position": 1,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1585,
    "name": "Documents",
    "required": false,
    "visible_for_clients": false,
    "checked_at": null,
    "parameters": [],
    "item_type": "header",
    "parent_id": null,
    "position": 2,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1586,
    "name": "Sign the inspection certificate",
    "required": false,
    "visible_for_clients": true,
    "checked_at": null,
    "parameters": [
      {
        "param_type": "text",
        "required": true,
        "value": null
      },
      {
        "param_type": "string",
        "required": true,
        "value": null
      }
    ],
    "item_type": "point",
    "parent_id": 1585,
    "planned_execution_in_hours": null,
    "position": 1,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1587,
    "name": "Check seal",
    "required": false,
    "visible_for_clients": false,
    "checked_at": null,
    "parameters": [],
    "item_type": "point",
    "parent_id": null,
    "planned_execution_in_hours": 1,
    "position": 3,
    "checked": false,
    "checked_by_user_id": null
  }
]

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "check_list": {
    "items": [
      {
        "name": "Check tightness",
        "item_type": "point"
      },
      {
        "name": "Documents",
        "item_type": "header",
        "children": [
          {
            "name": "Sign the inspection certificate",
            "item_type": "incorrect_type"
          }
        ]
      }
    ]
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "items": [
      {},
      {
        "children": [
          {
            "item_type": [
              "must be one of: point, header"
            ]
          }
        ]
      }
    ]
  }
}

Ticket checklist creation from template

POST`/api/v1/issues/{issue_id}/check_lists/templates/{template_id}/items{?api_token}`

Restriction of access rights

This method is only available for keys associated with agents who have access to actions “View the ticket”, “Create the checklist in the ticket”.
This method is not available for contact-associated keys.

Please note

Template ID is displayed in the list of templates when hovering over the name of the template.

URI example

POST https://<account>.okdesk.com/api/v1/issues/166/check_lists/templates/166/items?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 166
ticket ID.
template_id: integer (required) Example: 166
template ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 1584,
    "name": "Check tightness",
    "required": true,
    "visible_for_clients": true,
    "checked_at": null,
    "parameters": [
      {
        "param_type": "files",
        "required": true,
        "value": []
      },
      {
        "param_type": "text",
        "required": false,
        "value": null
      }
    ],
    "item_type": "point",
    "parent_id": null,
    "planned_execution_in_hours": 1,
    "position": 1,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1585,
    "name": "Documents",
    "required": false,
    "visible_for_clients": false,
    "checked_at": null,
    "parameters": [],
    "item_type": "header",
    "parent_id": null,
    "position": 2,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1586,
    "name": "Sign the inspection certificate",
    "required": false,
    "visible_for_clients": true,
    "checked_at": null,
    "parameters": [
      {
        "param_type": "text",
        "required": true,
        "value": null
      },
      {
        "param_type": "string",
        "required": true,
        "value": null
      }
    ],
    "item_type": "point",
    "parent_id": 1585,
    "planned_execution_in_hours": null,
    "position": 1,
    "checked": false,
    "checked_by_user_id": null
  },
  {
    "id": 1587,
    "name": "Check seal",
    "required": false,
    "visible_for_clients": false,
    "checked_at": null,
    "parameters": [],
    "item_type": "point",
    "parent_id": null,
    "planned_execution_in_hours": 1,
    "position": 3,
    "checked": false,
    "checked_by_user_id": null
  }
]

Response 404

HideShow

Applying checklist item

PATCH`/api/v1/issues/{issue_id}/check_lists/items/{item_id}/check{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
checked	boolean	required	Applying status of checklist item
item_parameters	associative array	optional	Parameters of checklist item

Restriction of access rights

This method is not available for contact-associated keys.
This method is only available for keys associated with agents who have access to actions “View the ticket”, “Apply the checklist in the ticket”.

Acceptable parameters of attachable files:

Name	Type	Mandatory	Description
attachment	string	required	Attachable file

Please note

The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
If there are already attached files in the changed checklist item, then when new files are attached, the old ones will be overwritten.

URI example

PATCH https://<account>.okdesk.com/api/v1/issues/166/check_lists/items/1002/check?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 166
ticket ID.
item_id: integer (required) Example: 1002
checklist item ID.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id": 1001,
        "name": "Check equipment",
        "required": false,
        "visible_for_clients": true,
        "checked_at": "2021-01-27T20:45:00.703+03:00",
        "parameters": [
            {
                "param_type": "text",
                "required": true,
                "value": "No leaks found"
            },
            {
                "param_type": "string",
                "required": true,
                "value": "51BKB835225"
            }
        ],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": 1,
        "position": 1,
        "checked_by_user_id": 2,
        "checked": true
    },
    {
        "id": 1002,
        "name": "Sign a contract",
        "required": true,
        "visible_for_clients": false,
        "checked_at": null,
        "parameters": [],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": null,
        "position": 2,
        "checked_by_user_id": null,
        "checked": false
    },
]

Request with attached files

HideShow

Headers

Content-Type: multipart/form-data

Body

curl -X PUT -H "Content-Type: multipart/form-data" -F "check_list_item[checked]=true"
-F "check_list_item[item_parameters][text]=No leaks found"
-F "check_list_item[item_parameters][files][0][attachment]=@/home/user/file.jpg"
https://<account>.okdesk.ru/api/v1/issues/12/check_lists/items/1001/check{?api_token}

where @/home/user/file.jpg is a path to the local file
for windows path will be like @"C:/myfile.txt"

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id": 1001,
        "name": "Check equipment",
        "required": false,
        "visible_for_clients": true,
        "checked_at": "2021-01-27T20:45:00.703+03:00",
        "parameters": [
            {
                "param_type": "text",
                "required": true,
                "value": "No leaks found"
            },
            {
                "param_type": "files",
                "required": false,
                "value": [
                    {
                        "id": 521,
                        "attachment_file_name": "check_photo.jpeg",
                        "attachment_file_size": 3243,
                        "created_at": "2021-04-23T17:20:27.937+03:00"
                    }
                ]
            }
        ],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": 1,
        "position": 1,
        "checked_by_user_id": 2,
        "checked": true
    },
    {
        "id": 1002,
        "name": "Sign a contract",
        "required": true,
        "visible_for_clients": false,
        "checked_at": null,
        "parameters": [],
        "item_type": "point",
        "parent_id": null,
        "planned_execution_in_hours": null,
        "position": 2,
        "checked_by_user_id": null,
        "checked": false
    },
]

Request with incorrect parameters

HideShow

Response 422

HideShow

Update Ticket

PATCH`/api/v1/issues/{issue_id}{?api_token}`

Valid request parameters:

Name	Type	Mandatory	Description
title	string	optional	Ticket title
description	string	optional	Ticket description

Access Rights Restrictions

The ticket update will only be performed if the user associated with the key has the rights to view the ticket and edit the ticket attributes according to the access rights settings. This method is not available for keys associated with contacts.

Please note

The title parameter cannot be passed with an empty value.

URI example

PATCH https://<account>.okdesk.com/api/v1/issues/763?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
Ticket ID.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "New title",
  "description": "New description",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Ticket info

GET`/api/v1/issues/{issue_id}{?api_token}`

Restriction of access rights

Ticket info will be provided if only the user associated with the key is entitled to view the ticket. Only limited information will be returned for contact-associated keys:

Subject;
Description;
Type;
Priority;
Registration date;
Resolution date;
Planned resolution date;
Date of the last update;
Delayed until;
Status;
Previous status (if the application is in the completed code status);
Rating;
Extended attributes, for which the display settings are set up in the client portal;
Responsible agent and coexecutors (if the corresponding value of the attribute “Show the ticket responsible agent and co-executors in the Client Portal” is set in the settings of the Client portal);
Group viewers and agent viewers (if the corresponding value of the attribute “Show ticket viewers in the Client portal” is set in the settings of the Client portal);
Company;
Contact;
List of public files of the ticket (without private/public tag);
The number of public comments and the date the last public comment was added;
Registration method.

Please note

File size (attachment_file_size) measured in bytes.

Please note

The value of Image-type extended attribute shall be returned as PNG image coded in base64.

URI example

GET https://<account>.okdesk.com/api/v1/issues/153?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 153
ticket ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 763,
  "title": "Web form ticket",
  "description": "",
  "created_at": "2016-03-15T18:05:17.568+03:00",
  "completed_at": "2016-05-19T10:54:09.987+03:00",
  "deadline_at": "2019-09-24T14:35:00.000+03:00",
  "source": "from_employee",
  "spent_time_total": 0,
  "start_execution_until": "2016-03-16T09:05:17.568+03:00",
  "planned_execution_in_hours": 12,
  "planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
  "reacted_at": "2016-04-10T18:43:44.951+03:00",
  "updated_at": "2016-08-23T09:39:35.428+03:00",
  "delayed_to": null,
  "company_id": 40,
  "group_id": 3,
  "coexecutors": [
    {
      "id": 3,
      "name": "John Mactavish",
      "group": {
        "id": 1,
        "name": "Targeting"
      }
    }
  ],
  "service_object_id": null,
  "equipment_ids": [],
  "attachments": [
    {
      "id": 8,
      "attachment_file_name": "photo.jpg",
      "description": "Photo of malfunction",
      "attachment_file_size": 4149,
      "is_public": false,
      "created_at": "2016-09-30T09:28:50.499+03:00"
    }
  ],
  "status_times": {
    "opened": {
      "total": "134 d, 15 h, 43 m",
      "on_schedule_total": "36 d, 1 h, 25 m"
    },
    "completed": {
      "total": "0 d, 0 h, 0 m",
      "on_schedule_total": "0 d, 0 h, 0 m"
    }
  },
  "parameters": [],
  "comments": {
    "count": 5,
    "last_at": "2018-07-05T16:06:10.000+03:00"
  },
  "parent_id": null,
  "child_ids": [],
  "type": {
    "id": 2,
    "code": "service",
    "name": "Service",
    "available_for_client": true
  },
  "priority": {
    "code": "low",
    "name": "Low"
  },
  "status": {
    "code": "opened",
    "name": "Opened"
  },
  "old_status": {
    "code": "completed",
    "name": "Completed"
  },
  "rate": {
    "id": 3,
    "value": "normal"
  },
  "address": {
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "value": "3709 Charter Street, Overland Park, KS 66210"
  },
  "observers": [
    {
      "id": 113,
      "type": "employee",
      "name": "Adam Jensen"
    },
    {
      "id": 121,
      "type": "employee",
      "name": "Robert Bob Page"
    }
  ],
  "observer_groups": [
    {
      "id": 5,
      "name": "Quality control"
    }
  ],
  "contact": {
    "id": 3020,
    "name": "Sally Housecoat"
  },
  "agreement": null,
  "assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "author": {
    "id": 3020,
    "name": "Sally Housecoat"
  }
}

Ticket deletion

DELETE`/api/v1/issues/{issue_id}{?api_token}`

Restriction of access rights

Deletion of a ticket is available to agents in accordance with the settings of access rights. This method is not available for contact-associated keys.

URI example

DELETE https://<account>.okdesk.com/api/v1/issues/153?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 153
ticket ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "result": "",
  "issue": {
    "id": 153,
    "title": "Service man is required",
    "description": "",
    "created_at": "2016-09-30T09:28:50.499+03:00",
    "completed_at": null,
    "deadline_at": "2016-09-30T17:28:50.000+03:00",
    "updated_at": "2016-09-30T10:34:22.000+03:00",
    "delayed_to": null,
    "source": "from_email",
    "spent_time_total": 6.5,
    "start_execution_until": "2019-09-01T00:00:00.000+03:00",
    "planned_execution_in_hours": 12.5,
    "planned_reaction_at": "2016-10-22T13:00:00.000+03:00",
    "reacted_at": "2016-10-15T15:31:14.383+03:00",
    "company_id": 86,
    "group_id": 3,
    "service_object_id": 3,
    "parameters": [
      {
        "code": "address",
        "name": "Call address",
        "field_type": "ftstring",
        "value": "54 Churchill Street"
      }
    ],
    "parent_id": 102,
    "status": {
      "code": "opened",
      "name": "Opened"
    },
    "old_status": {
      "code": "completed",
      "name": "Completed"
    },
    "assignee": {
      "id": 4,
      "name": "Max Mustermann"
    },
    "author": {
      "id": 44,
      "name": "Jean Dupont"
    },
    "agreement": {
      "id": 34,
      "title": "Service contract",
      "company_ids": [
        1
      ]
    },
    "contact": {
      "id": 44,
      "name": "Jean Dupont"
    },
    "priority": {
      "code": "low",
      "name": "Low"
    },
    "type": {
      "code": "service",
      "name": "Service"
    }
  }
}

Equipment ¶

Equipment search

GET`/api/v1/equipments/{?api_token,serial_number,inventory_number,search_string}`

The search is carried out by the exact match of the serial number or inventory number or by substring

Restriction of access rights

Equipment search will be performed only if a key-related agent has access to the list of equipment in accordance with the settings of access rights. This method is not available for contact-associated keys.

Please note

When transferring the search_string parameter, the other parameters are not considered

URI example

GET https://<account>.okdesk.com/api/v1/equipments/?api_token=3e9a214215f493c4&serial_number=51BKB835225&inventory_number=1101040003532&search_string=desk

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
inventory_number: string (optional) Example: 1101040003532
Equipment inventory number
serial_number: string (optional) Example: 51BKB835225
Equipment serial number
search_string: string (optional) Example: desk
Target substring

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 3,
  "serial_number": "1101040003532",
  "inventory_number": "51BKB835225",
  "maintenance_entity_id": 15,
  "parent_id": 43,
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Laptop",
    "description": ""
  },
  "equipment_manufacturer": null,
  "equipment_model": null,
  "company": {
    "id": 45,
    "name": "Newco",
    "additional_name": null,
    "site": "intellectplus.com",
    "email": "intel+@okdesk.com",
    "phone": "+8412 381312",
    "address": "60 Wall Street, New York City",
    "comment": "",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Photo of malfunction",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2016-09-30T09:28:50.499+03:00"
      }
    ]
  },
  "parameters": [
    {
      "code": "end_of_service_period",
      "name": "Service term completion date",
      "field_type": "ftdate",
      "value": "2018-03-16"
    },
    {
      "code": "color",
      "name": "Color",
      "field_type": "ftstring",
      "value": "black"
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Important Contract"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Description",
      "is_public": true,
      "id": 575
    }
  ]
}

Creation of equipment

POST`/api/v1/equipments/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
equipment_type_code	string	required	Equipment type code
equipment_manufacturer_code	string	optional	Equipment manufacturer code
equipment_model_code	string	optional	Equipment model code
serial_number	string	optional	Serial number
inventory_number	string	optional	Inventory number
comment	string	optional	Comment
company_id	string	optional	The ID of the company linked to the equipment
maintenance_entity_id	string	optional	The ID of the service aim, to which the equipment is linked
parent_id	string	optional	Parent equipment ID
custom_parameters	associative array	optional	Equipment extended attributes
agreement_ids	associative array	optional	Set of equipment contract IDs

Please note

If the equipment_type_code or equipment_manufacturer_code does not correspond to the type and manufacturer codes of the equipment model (equipment_model_code), the equipment will not be created.
If the service aim ID (maintenance_entity_id) does not correspond to the company’s ID (company_id), the equipment will not be created.
If the contract ID from array (agreement_ids) does not correspond to the company’s ID (company_id), the equipment will not be created.
The equipment being created and parent equipment shall be associated with the same company and same service aim.

Restriction of access rights

Creation of equipment is available to agents in accordance with the settings of access rights.

It is only possible to specify a link with a company if the key-linked agent has the right to add equipment to the company in accordance with the access rights settings.
Specifying a service aim will be possible only if the key-linked agent has the right to add equipment to the service aim in accordance with the settings of access rights.
Contracts can be specified only if the agent associated with the key has the right to edit the equipment binding to the contract in accordance with the access rights settings.
This method is not available for contact-associated keys.

URI example

POST https://<account>.okdesk.com/api/v1/equipments/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "equipment": {
    "equipment_type_code": "laptop",
    "equipment_manufacturer_code": "Asus",
    "equipment_model_code": "K53sm",
    "serial_number": "51BKB835225",
    "inventory_number": "11010400003532",
    "comment": "The K53SM laptop uses NVIDIA® GeForce® 630M discrete graphics engine with 2 gigabyte video RAM. This will be enough for modern computer games and multimedia applications.",
    "company_id": "4",
    "maintenance_entity_id": "15",
    "parent_id": "74",
    "custom_parameters": {
      "end_of_service_period": "16/03/2018",
      "color": "black"
    },
    "agreement_ids": [
      2
    ]
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 3,
  "serial_number": "1101040003532",
  "inventory_number": "51BKB835225",
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Laptop",
    "description": null
  },
  "equipment_manufacturer": {
    "id": 1,
    "code": "asus",
    "name": "Asus",
    "description": null
  },
  "equipment_model": {
    "id": 1,
    "code": "k53sm",
    "name": "K53sm",
    "description": null
  },
  "company": {
    "id": 4,
    "name": "Newco",
    "additional_name": null,
    "site": "intellectplus.com",
    "email": "intel+@okdesk.com",
    "phone": "+8412 381312",
    "address": "60 Wall Street, New York City",
    "comment": "",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Photo of malfunction",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2016-09-30T09:28:50.499+03:00"
      }
    ]
  },
  "comment": "The K53SM laptop uses NVIDIA® GeForce® 630M discrete graphics engine with 2 gigabyte video RAM. This will be enough for modern computer games and multimedia applications.",
  "maintenance_entity_id": 15,
  "parent_id": 74,
  "parameters": [
    {
      "code": "end_of_service_period",
      "name": "Service term completion date",
      "field_type": "ftdate",
      "value": "2018-03-16"
    },
    {
      "code": "color",
      "name": "Color",
      "field_type": "ftstring",
      "value": "black"
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Important Contract"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Description",
      "is_public": true,
      "id": 575
    }
  ]
}

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "equipment": {
    "equipment_type_code": "laptop",
    "equipment_manufacturer_code": "Siemens",
    "equipment_model_code": "x989",
    "serial_number": "51BKB835225",
    "inventory_number": "11010400003532",
    "company_id": "456",
    "maintenance_entity_id": "77",
    "parent_id": "54",
    "custom_parameters": {
      "package": "premium"
    }
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "equipment_manufacturer": [
      "Entry Siemens does not exist"
    ],
    "company": [
      "Entry 456 does not exist"
    ],
    "equipment_model_rule": [
      "Equipment type code or equipment manufacturer code do not match the equipment model"
    ],
    "maintenance_entity_exists_in_company_scope": [
      "Service aim %{maintenance_entity_id} for the assigned company does not exist 22"
    ],
    "custom_parameters": [
      {
        "package": "Values of the extended parameter Package are missing in the list of values: premium"
      }
    ]
  }
}

Editing of equipment

PATCH`/api/v1/equipments/{id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
equipment_type_code	string	optional	Equipment type code
equipment_manufacturer_code	string	optional	Equipment manufacturer code
equipment_model_code	string	optional	Equipment model code
serial_number	string	optional	Serial number
inventory_number	string	optional	Inventory number
comment	string	optional	Comment
company_id	string	optional	The ID of the company linked to the equipment
maintenance_entity_id	string	optional	The ID of the service aim, to which the equipment is linked
parent_id	string	optional	Parent equipment ID
custom_parameters	associative array	optional	Equipment extended attributes
agreement_ids	associative array	optional	Set of equipment contract IDs

Please note

If the equipment_type_code or equipment_manufacturer_code does not correspond to the type and manufacturer codes of the equipment model (equipment_model_code), the equipment will not be created.
If the service aim ID (maintenance_entity_id) does not correspond to the company’s ID (company_id), the equipment will not be changed.
If the contract ID from array (agreement_ids) does not correspond to the company’s ID (company_id), the equipment will not be changed.
When sending an empty array in the agreement_ids parameter all contracts will be removed from the equipment
When sending an empty string or null in the serial_number, inventory_number, comment, company_id, maintenance_entity_id parameters this attributes will be removed from the equipment.
The equipment being changed and parent equipment shall be associated with the same company and same service aim.

Restriction of access rights

Editing of equipment will be performed only if a key-related agent has rights to review the equipment and edit equipment attributes in accordance with the settings of access rights.
It is only possible to specify a link with a company if the key-linked agent has the right to add equipment to the company in accordance with the access rights settings.
Specifying a service aim will be possible only if the key-linked agent has the right to add equipment to the service aim in accordance with the settings of access rights.
Specifying a contract will be possible only if the key-linked agent has the right to add equipment to the contract in accordance with the settings of access rights.
This method is not available for contact-associated keys.

URI example

PATCH https://<account>.okdesk.com/api/v1/equipments/13?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 13
Equipment ID.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "equipment": {
    "equipment_model_code": "x50sm",
    "company_id": "4",
    "maintenance_entity_id": "15",
    "custom_parameters": {
      "end_of_service_period": "16/03/2019"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 3,
  "serial_number": "1101040003532",
  "inventory_number": "51BKB835225",
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Laptop",
    "description": null
  },
  "equipment_manufacturer": {
    "id": 1,
    "code": "asus",
    "name": "Asus",
    "description": null
  },
  "equipment_model": {
    "id": 4,
    "code": "x50sm",
    "name": "x50sm",
    "description": null
  },
  "company": {
    "id": 4,
    "name": "Newco",
    "additional_name": null,
    "site": "intellectplus.com",
    "email": "intel+@okdesk.com",
    "phone": "+8412 381312",
    "address": "60 Wall Street, New York City",
    "comment": "",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Photo of malfunction",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2016-09-30T09:28:50.499+03:00"
      }
    ]
  },
  "comment": "The K53SM laptop uses NVIDIA® GeForce® 630M discrete graphics engine with 2 gigabyte video RAM. This will be enough for modern computer games and multimedia applications.",
  "maintenance_entity_id": 15,
  "parent_id": 23,
  "parameters": [
    {
      "code": "end_of_service_period",
      "name": "Service term completion date",
      "field_type": "ftdate",
      "value": "2018-03-16"
    },
    {
      "code": "color",
      "name": "Color",
      "field_type": "ftstring",
      "value": "black"
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Important Contract"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Description",
      "is_public": true,
      "id": 575
    }
  ]
}

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "equipment": {
    "equipment_model_code": "x989",
    "serial_number": "51BKB835225",
    "inventory_number": "11010400003532",
    "company_id": "456",
    "parent_id": "89",
    "maintenance_entity_id": "77",
    "custom_parameters": {
      "package": "premium"
    }
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "company": [
      "Entry 456 does not exist"
    ],
    "equipment_model_rule": [
      "Equipment type code or equipment manufacturer code do not match the equipment model"
    ],
    "maintenance_entity_exists_in_company_scope": [
      "Service aim %{maintenance_entity_id} for the assigned company does not exist 22"
    ],
    "custom_parameters": [
      {
        "package": "Values of the extended parameter Package are missing in the list of values: premium"
      }
    ]
  }
}

Equipment info

GET`/api/v1/equipments/{id}{?api_token}`

Restriction of access rights

Information on equipment will be provided only if a key-related agent has rights to review the equipment in accordance with the settings of access rights. This method is not available for contact-associated keys.

URI example

GET https://<account>.okdesk.com/api/v1/equipments/13?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 13
Equipment ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 7,
  "serial_number": "51BKB835225",
  "inventory_number": "909786543",
  "comment": "Laptop Asus K53sm",
  "company": "Newco",
  "maintenance_entity_id": 15,
  "parent_id": 23,
  "parameters": [
    {
      "code": "attr1",
      "name": "Extended warranty",
      "field_type": "ftstring",
      "value": "36 months"
    },
    {
      "code": "attr2",
      "name": "Sale date",
      "field_type": "ftdate",
      "value": "2018-07-06"
    },
    {
      "code": "attr3",
      "name": "Accepted for repairs",
      "field_type": "ftdatetime",
      "value": "2018-09-21T14:11:00.000+03:00"
    },
    {
      "code": "attr4",
      "name": "Warranty claim",
      "field_type": "ftcheckbox",
      "value": true
    },
    {
      "code": "attr5",
      "name": "Operating system",
      "field_type": "ftselect",
      "value": "Windows 10"
    },
    {
      "code": "attr6",
      "name": "Diagnostics",
      "field_type": "ftmultiselect",
      "value": [
        "Disk",
        "Motherboard"
      ]
    }
  ],
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Laptop",
    "description": ""
  },
  "equipment_manufacturer": {
    "id": 1,
    "code": "asus",
    "name": "Asus",
    "description": ""
  },
  "equipment_model": {
    "id": 4,
    "code": "x50sm",
    "name": "x50sm",
    "description": ""
  },
  "agreements": [
    {
      "id": 2,
      "title": "Important Contract"
    }
  ]
}

Obtaining list by parameters

GET`/api/v1/equipments/list/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
company_ids	array of integer	optional	Array of company IDs (set the value “0” to the parameter to show equipment without a company). Example: company_ids[]=1
maintenance_entity_ids	array of integer	optional	Array of maintenance entity IDs (set the value “0” to the parameter to show equipment without a maintenance entity). Example: maintenance_entity_ids[]=1
agreement_ids	array of integer	optional	Array of contract IDs (set the value “0” to the parameter to show equipment without a contract). Example: agreement_ids[]=1
created_since	string	optional	The date equipment was created in the account’s time zone (From) Example: created_since=2019-05-25
created_until	string	optional	The date equipment was created in the account’s time zone (Until) Example: created_until=2019-05-25
equipment_kind_codes	array of string	optional	Array of equipment kind codes. Example: equipment_kind_codes[]=EG
equipment_manufacterer_codes	array of string	optional	Array of equipment manufacterer codes. Example: equipment_manufacturer_codes[]=EG
equipment_model_codes	array of string	optional	Array of equipment model codes. Example: equipment_model_codes[]=EG
custom_parameters	associative array	optional	Associative array of Extended attribute code pairs: Value or set of values
page	associative array	optional	Associative array of parameters for a per-page display of the equipment list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the equipment starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment’s lowest id. Example: page[direction]=forward

Restriction of access rights

This method is not available for contact-associated keys.
This method is only available for keys associated with agents who have access to actions “Add to equipment list”, “View enlisted equipment”

Please note

This method returns no more than 100 entries.
If the parameters of per-page display are not transferred, the list of the last 100 equipment created will be returned.

Valid values of extended attributes:

Parameter type	Type	Description
Date	string	There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12
Date/time	string	There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12
Checkbox	string	Two values – true and false – are available. Example: custom_parameters[checkbox_code]=true
List item	array of string	An array of list values. Example: custom_parameters[list_code][]=list_value
List item set	array of string	An array of list values. Example: custom_parameters[list_code][]=list_value

An example of a query with the equipment list per-page display parameters

https://<account>.okdesk.com/api/v1/equipments/list?api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward

URI example

GET https://<account>.okdesk.com/api/v1/equipments/list/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 32,
    "serial_number": "123",
    "inventory_number": "321",
    "parameters": [
      {
        "code": "checkbox_sample",
        "name": "checkbox_sample",
        "field_type": "ftcheckbox",
        "value": true
      }
    ],
    "company": {
      "id": 113,
      "name": "SomeCompany"
    },
    "maintenance_entity": null,
    "parent_id": 39,
    "equipment_kind": {
      "id": 5,
      "code": "some_lind",
      "name": "some_kind",
      "description": ""
    },
    "equipment_manufacturer": null,
    "equipment_model": null,
    "agreements": [
      {
        "id": 2,
        "title": "Important Contract"
      }
    ]
  }
]

Attaching files to a equipment

POST`/api/v1/equipments/{id}/attachments/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
attachments	array	required	List of attached files

Valid query attached files parameters:

Name	Type	Mandatory	Description
attachment	string	required	Attachable file
description	string	optional	File description
is_public	boolean	optional	File availability

Please note

The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
If parameter is_public is not sent, availability flag for the attachable files will be equal to the value of settings parameter ‘Files by default’

Restriction of access rights

Adding a file to a equipment is available to agents in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

URI example

POST https://<account>.okdesk.com/api/v1/equipments/3/attachments/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 3
equipment ID.

Request with attached files

HideShow

Headers

Content-Type: multipart/form-data

Body

curl  -H "Content-Type: multipart/form-data"
-F "equipment[attachments][0][attachment]=@/home/user/file.jpg"
-F "equipment[attachments][0][is_public]=true"
-F "equipment[attachments][0][description]=Description"
https://<account>.okdesk.ru/api/v1/equipments/{id}/attachments/{?api_token}

where @/home/user/file.jpg is a path to the local file
for windows path will be like @"C:/myfile.txt"

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 3,
  "serial_number": "1101040003532",
  "inventory_number": "51BKB835225",
  "maintenance_entity_id": 15,
  "parent_id": 43,
  "equipment_kind": {
    "id": 24,
    "code": "laptop",
    "name": "Laptop",
    "description": ""
  },
  "equipment_manufacturer": null,
  "equipment_model": null,
  "company": {
    "id": 45,
    "name": "Newco",
    "additional_name": null,
    "site": "intellectplus.com",
    "email": "intel+@okdesk.com",
    "phone": "+8412 381312",
    "address": "60 Wall Street, New York City",
    "comment": "",
    "attachments": [
      {
        "id": 8,
        "attachment_file_name": "photo.jpg",
        "description": "Photo of malfunction",
        "attachment_file_size": 4149,
        "is_public": false,
        "created_at": "2016-09-30T09:28:50.499+03:00"
      }
    ]
  },
  "parameters": [
    {
      "code": "end_of_service_period",
      "name": "Service term completion date",
      "field_type": "ftdate",
      "value": "2018-03-16"
    },
    {
      "code": "color",
      "name": "Color",
      "field_type": "ftstring",
      "value": "black"
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Important Contract"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Description",
      "is_public": true,
      "id": 575
    }
  ]
}

Service aims ¶

Service aim search

GET`/api/v1/maintenance_entities/{?api_token,name,comment,search_string}`

The search is carried out by the exact match of the service aim name, comment or by substring

Please note

If the names of multiple service aims match, all values fit the search criteria will be returned When transferring the search_string parameter, the other parameters are not considered

Restriction of access rights

The service aim search will be performed only if the key-linked agent has access to a service aim list in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

URI example

GET https://<account>.okdesk.com/api/v1/maintenance_entities/?api_token=3e9a214215f493c4&name=Sales outlet No.13&comment=Comment&search_string=desk

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
name: string (optional) Example: Sales outlet No.13
Name
comment: string (optional) Example: Comment
Service aim additional info
search_string: string (optional) Example: desk
Target substring

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "name": "Sales outlet No.13",
    "address": null,
    "comment": null,
    "default_assignee_id": 12,
    "default_assignee_group_id": 1,
    "company_id": 1040,
    "active": true,
    "timezone": {
      "code": "Moscow",
      "name": "Moscow",
      "gmt": "+03:00"
    },
    "contacts_ids": [
      23,
      24,
      63,
      64,
      65
    ],
    "equipments_ids": [
      8,
      9
    ],
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "parameters": [
      {
        "code": "attr1",
        "name": "Document No.",
        "field_type": "ftstring",
        "value": "2368590"
      },
      {
        "code": "attr2",
        "name": "Commencement date",
        "field_type": "ftdate",
        "value": "2019-02-06"
      },
      {
        "code": "attr3",
        "name": "Date of the next call",
        "field_type": "ftdatetime",
        "value": "2019-02-21T14:00:00.000+03:00"
      },
      {
        "code": "attr4",
        "name": "VIP Service",
        "field_type": "ftcheckbox",
        "value": true
      },
      {
        "code": "attr5",
        "name": "Type of activity",
        "field_type": "ftselect",
        "value": "Software"
      },
      {
        "code": "attr6",
        "name": "Types of premises",
        "field_type": "ftmultiselect",
        "value": [
          "Head office",
          "Recreation area"
        ]
      }
    ],
    "schedule": {
      "id": 1,
      "name": "On weekdays, 9 a.m. to 6 p.m."
    },
    "observers": [
      {
        "id": 5,
        "name": "Andrei Russo"
      },
      {
        "id": 12,
        "name": "Alix Mckay"
      }
    ],
    "observer_groups": [
      {
        "id": 23,
        "name": "Mechanics"
      },
      {
        "id": 3,
        "name": "Drivers"
      }
    ],
    "attachments": [
      {
        "attachment_file_name": "file.jpg",
        "description": "Description",
        "is_public": true,
        "id": 575
      }
    ],
    "agreements": [
      {
        "id": 2,
        "title": "Important Contract"
      }
    ]
  }
]

Creating a service aim

POST`/api/v1/maintenance_entities/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	required	Name
company_id	integer	required	Company ID
agreement_ids	array of int	optional	Contracts IDs
address	string	optional	Address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc.
coordinates	array of float	optional	Service aim coordinates
timezone	string	optional	Service aim time zone
comment	string	optional	Service aim additional info
default_assignee_id	integer	optional	ID of responsible agent by default
default_assignee_group_id	integer	optional	ID of responsible group by default
schedule_id	integer	optional	Service aim schedule ID
observer_ids	array of int	optional	Array of IDs of users viewing the service aim
observer_group_ids	array of int	optional	Array of IDs of agent groups viewing the service aim
custom_parameters	associative array	optional	Extended attributes of service aim

Please note

The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude). The agreement_ids parameter must contain IDs of contracts of a company with company_id.

Restriction of access rights

Creating a service aim is available to agents in accordance with the settings of access rights. It is only possible to specify a link with a company if the key-linked agent has the right to add a service aim to the company in accordance with the access rights settings. Specifying contracts is possible only if the agent associated with the key has the right to edit the link of the service aim to the contract in accordance with the access rights settings. This method is not available for keys linked to contact persons.

URI example

POST https://<account>.okdesk.com/api/v1/maintenance_entities/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "maintenance_entity": {
    "name": "Sales outlet No.13",
    "company_id": 1040,
    "agreement_ids": [
      2
    ],
    "address": "3709 Charter Street, Overland Park, KS 66210",
    "comment": "Comment",
    "default_assignee_id": 12,
    "default_assignee_group_id": 1,
    "timezone": "Moscow",
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "schedule_id": 1,
    "observer_ids": [
      5,
      12
    ],
    "custom_parameters": {
      "code1": "123456789",
      "code2": "2019-02-15",
      "code3": true
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 9,
  "name": "Sales outlet No.13",
  "address": "3709 Charter Street, Overland Park, KS 66210",
  "comment": "Comment",
  "default_assignee_id": 12,
  "default_assignee_group_id": 1,
  "company_id": 1040,
  "active": true,
  "timezone": {
    "code": "Moscow",
    "name": "Moscow",
    "gmt": "+03:00"
  },
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "parameters": [
    {
      "code": "code1",
      "name": "Document No.",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Commencement date",
      "field_type": "ftdate",
      "value": "2019-02-15"
    },
    {
      "code": "code3",
      "name": "VIP Service",
      "field_type": "ftcheckbox",
      "value": true
    }
  ],
  "schedule": {
    "id": 1,
    "name": "On weekdays, 9 a.m. to 6 p.m."
  },
  "observers": [
    {
      "id": 5,
      "name": "Robyn Fuller"
    },
    {
      "id": 12,
      "name": "Alix Mckay"
    }
  ],
  "observer_groups": [],
  "attachments": [],
  "agreements": [
    {
      "id": 2,
      "title": "Important Contract"
    }
  ]
}

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "maintenance_entity": {
    "name": "Sales outlet No.13",
    "company_id": 9999999,
    "address": "3709 Charter Street, Overland Park, KS 66210",
    "comment": "Comment",
    "default_assignee_id": 12,
    "default_assignee_group_id": 1
  }
}

Response 422

HideShow

Editing a service aim

PATCH`/api/v1/maintenance_entities/{id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	optional	Name
company_id	integer	optional	Company ID
agreement_ids	array of int	optional	Contracts IDs
address	string	optional	Address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc.
coordinates	array of float	optional	Service aim coordinates
timezone	string	optional	Service aim time zone
comment	string	optional	Service aim additional info
default_assignee_id	integer	optional	ID of responsible agent by default
default_assignee_group_id	integer	optional	ID of responsible group by default
schedule_id	integer	optional	Service aim schedule ID
observer_ids	array of int	optional	Array of IDs of users viewing the service aim
observer_group_ids	array of int	optional	Array of IDs of agent groups viewing the service aim
custom_parameters	associative array	optional	Extended attributes of service aim

Please note

name parameter can not be transferred with an empty value

The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude). The agreement_ids parameter must contain IDs of contracts of an edited service aim company.

Restriction of access rights

Editing a service aim will be possible only if the key-linked agent has the rights to view the service aim and edit the service aim attributes in accordance with the settings of access rights. It is only possible to specify a link with a company if the key-linked agent has the right to add a service aim to the company in accordance with the access rights settings. Specifying contracts is possible only if the agent associated with the key has the right to edit the link of the service aim to the contract in accordance with the access rights settings. This method is not available for keys linked to contact persons.

URI example

PATCH https://<account>.okdesk.com/api/v1/maintenance_entities/4?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 4
Service aim ID.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "maintenance_entity": {
    "name": "Shop No. 15",
    "agreement_ids": [
      3
    ],
    "address": "2537 Goldie Lane, Cincinnati, OH 45203",
    "default_assignee_id": 14,
    "default_assignee_group_id": 1,
    "timezone": "Samara",
    "schedule_id": 1,
    "observer_group_ids": [
      7
    ],
    "coordinates": [
      53.2184321,
      44.9998082
    ],
    "custom_parameters": {
      "code2": "2019-02-15"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 9,
  "name": "Shop No. 15",
  "address": "2537 Goldie Lane, Cincinnati, OH 45203",
  "comment": "Comment",
  "default_assignee_id": 14,
  "default_assignee_group_id": 1,
  "company_id": 1040,
  "active": true,
  "timezone": {
    "code": "Samara",
    "name": "Samara",
    "gmt": "+04:00"
  },
  "coordinates": [
    53.2184321,
    44.9998082
  ],
  "parameters": [
    {
      "code": "code1",
      "name": "Document No.",
      "field_type": "ftstring",
      "value": "123456789"
    },
    {
      "code": "code2",
      "name": "Commencement date",
      "field_type": "ftdate",
      "value": "2019-02-15"
    },
    {
      "code": "code3",
      "name": "VIP Service",
      "field_type": "ftcheckbox",
      "value": true
    }
  ],
  "schedule": {
    "id": 1,
    "name": "On weekdays, 9 a.m. to 6 p.m."
  },
  "observers": [],
  "observer_groups": [
    {
      "id": 7,
      "name": "Electricians"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Description",
      "is_public": true,
      "id": 575
    }
  ],
  "agreements": [
    {
      "id": 3,
      "title": "Another Important Contract"
    }
  ]
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Service aim info

GET`/api/v1/maintenance_entities/{id}{?api_token}`

Restriction of access rights

Service aim info will be provided only if the key-linked agent has the right to view the service aim in accordance with the settings of access rights.

URI example

GET https://<account>.okdesk.com/api/v1/maintenance_entities/153?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 153
Service aim ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "name": "Newco Service Center"
    "2365 Shobe Lane, Durango, CO 81301"
    "comment": "",
    "default_assignee_id": 12,
    "default_assignee_group_id": 1,
    "company_id": 1,
    "active": true,
    "timezone": {
        "code": "Kaliningrad",
        "name": "Kaliningrad",
        "gmt": "+02:00"
    },
    "contacts_ids": [
        23,
        24,
        63,
        64,
        65
    ],
    "equipments_ids": [
        8,
        9
    ],
    "coordinates": [
        53.2605796,
        49.9179003
    ],
    "parameters": [
        {
            "code": "attr1",
            "name": "Document No.",
            "field_type": "ftstring",
            "value": "2368590"
        },
        {
            "code": "attr2",
            "name": "Commencement date",
            "field_type": "ftdate",
            "value": "2019-02-06"
        },
        {
            "code": "attr3",
            "name": "Date of the next call",
            "field_type": "ftdatetime",
            "value": "2019-02-21T14:00:00.000+03:00"
        },
        {
            "code": "attr4",
            "name": "VIP Service",
            "field_type": "ftcheckbox",
            "value": true
        },
        {
            "code": "attr5",
            "name": "Type of activity",
            "field_type": "ftselect",
            "value": "Software"
        },
        {
            "code": "attr6",
            "name": "Types of premises",
            "field_type": "ftmultiselect",
            "value": [
                "Head office",
                "Recreation area"
            ]
        }
    ],
    "schedule": {
        "id": 1,
        "name": "On weekdays, 9 a.m. to 6 p.m."
    },
    "observers": [
        {
            "id": 5,
            "name": "Jareth Charles"
        }
    ],
    "observer_groups": [
        {
            "id": 7,
            "name": "Electricians"
        }
    ],
    "attachments": [
        {
            "attachment_file_name": "file.jpg",
            "description": "Description",
            "is_public": true,
            "id": 575
        }
    ],
    "agreements": [
        {
            "id": 2,
            "title": "Important Contract"
        }
    ]
}

Obtaining list by parameters

GET`/api/v1/maintenance_entities/list{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
company_ids	array of integer	optional	Array of company IDs. Example: company_ids[]=1
agreement_ids	array of integer	optional	Array of contract IDs (set the value “0” to the parameter to show service aims without a contract). Example: agreement_ids[]=1
default_assignee_ids	array of integer	optional	Array of responsible agent IDs (set the value “0” to the parameter to show service aims without a responsible agent). Example: default_assignee_ids[]=1
default_assignee_group_ids	array of integer	optional	Array of responsible group IDs (set the value “0” to the parameter to show service aims without a responsible group). Example: default_assignee_group_ids[]=1
created_since	string	optional	The date the service aim was created in the account’s time zone (From) Example: created_since=2019-05-25
created_until	string	optional	The date the service aim was created in the account’s time zone (Until) Example: created_until=2019-05-25
updated_since	string	optional	The date the service aim was modified in the account’s time zone (From) Example: updated_since=2019-05-25
updated_until	string	optional	The date the service aim was modified in the account’s time zone (Until) Example: updated_until=2019-05-25
page	associative array	optional	Associative array of parameters for a per-page display of the service aim list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the service aim starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the service aim id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the service aim’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the service aim’s lowest id. Example: page[direction]=forward

Restriction of access rights

The list of service aims will be provided only if the key-linked agent has access to a service aim list in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 service aims created will be returned.

An example of a query with the service aim list per-page display parameters

https://<account>.okdesk.com/api/v1/maintenance_entities/list?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward

URI example

GET https://<account>.okdesk.com/api/v1/maintenance_entities/list?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 8,
    "name": "Aim No.2",
    "address": "Anytown",
    "coordinates": [
      55.755831,
      37.617673
    ],
    "company_id": 1,
    "active": true,
    "agreements": [
      {
        "id": 1,
        "title": "Important Contract"
      }
    ],
    "parameters": [
      {
        "code": "attr1",
        "name": "Document No.",
        "field_type": "ftstring",
        "value": "2368590"
      }
    ]
  },
  {
    "id": 5,
    "name": "Aim No.1",
    "address": "Your Town",
    "coordinates": [
      59.869778,
      30.278344
    ],
    "company_id": 3,
    "active": true,
    "agreements": [],
    "parameters": [
      {
        "code": "attr1",
        "name": "Document No.",
        "field_type": "ftstring",
        "value": "1168590"
      }
    ]
  }
]

Attaching files to a service aim

POST`/api/v1/maintenance_entities/{id}/attachments/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
attachments	array	required	List of attached files

Valid query attached files parameters:

Name	Type	Mandatory	Description
attachment	string	required	Attachable file
description	string	optional	File description
is_public	boolean	optional	File availability

Please note

The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
If parameter is_public is not sent, availability flag for the attachable files will be equal to the value of settings parameter ‘Files by default’

Restriction of access rights

Adding a file to a service aim is available to agents in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

URI example

POST https://<account>.okdesk.com/api/v1/maintenance_entities/153/attachments/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 153
service aim ID.

Request with attached files

HideShow

Headers

Content-Type: multipart/form-data

Body

curl  -H "Content-Type: multipart/form-data"
-F "maintenance_entity[attachments][0][attachment]=@/home/user/file.jpg"
-F "maintenance_entity[attachments][0][is_public]=true"
-F "maintenance_entity[attachments][0][description]=Description"
https://<account>.okdesk.ru/api/v1/maintenance_entities/{id}/attachments/{?api_token}

where @/home/user/file.jpg is a path to the local file
for windows path will be like @"C:/myfile.txt"

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "name": "Newco Service Center"
    "2365 Shobe Lane, Durango, CO 81301"
    "comment": "",
    "default_assignee_id": 12,
    "default_assignee_group_id": 1,
    "company_id": 1,
    "active": true,
    "timezone": {
        "code": "Moscow",
        "name": "Moscow",
        "gmt": "+03:00"
    },
    "contacts_ids": [
        23,
        24,
        63,
        64,
        65
    ],
    "equipments_ids": [
        8,
        9
    ],
    "coordinates": [
        53.2605796,
        49.9179003
    ],
    "parameters": [
        {
            "code": "attr1",
            "name": "Document No.",
            "field_type": "ftstring",
            "value": "2368590"
        },
        {
            "code": "attr2",
            "name": "Commencement date",
            "field_type": "ftdate",
            "value": "2019-02-06"
        },
        {
            "code": "attr3",
            "name": "Date of the next call",
            "field_type": "ftdatetime",
            "value": "2019-02-21T14:00:00.000+03:00"
        },
        {
            "code": "attr4",
            "name": "VIP Service",
            "field_type": "ftcheckbox",
            "value": true
        },
        {
            "code": "attr5",
            "name": "Type of activity",
            "field_type": "ftselect",
            "value": "Software"
        },
        {
            "code": "attr6",
            "name": "Types of premises",
            "field_type": "ftmultiselect",
            "value": [
                "Head office",
                "Recreation area"
            ]
        }
    ],
    "schedule": {
        "id": 1,
        "name": "On weekdays, 9 a.m. to 6 p.m."
    },
    "observers": [],
    "observer_groups": [],
    "attachments": [
        {
            "attachment_file_name": "file.jpg",
            "description": "Description",
            "is_public": true,
            "id": 575
        }
    ],
    "agreements": [
        {
            "id": 2,
            "title": "Important Contract"
        }
    ]
}

Archiving service aim

PATCH`/api/v1/maintenance_entities/{id}/activations{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
active	boolean	required	Service aim activation status

Restriction of access rights

Service aim archiving is available to agents in accordance with the settings of access rights.

URI example

PATCH https://<account>.okdesk.com/api/v1/maintenance_entities/1/activations?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 1
service aim ID.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "name": "Sales outlet No.13",
  "address": null,
  "comment": null,
  "default_assignee_id": 12,
  "default_assignee_group_id": 1,
  "company_id": 1040,
  "active": true,
  "timezone": {
    "code": "Moscow",
    "name": "Moscow",
    "gmt": "+03:00"
  },
  "contacts_ids": [
    23,
    24,
    63,
    64,
    65
  ],
  "equipments_ids": [
    8,
    9
  ],
  "coordinates": null,
  "parameters": [
    {
      "code": "attr1",
      "name": "Document No.",
      "field_type": "ftstring",
      "value": "2368590"
    },
    {
      "code": "attr2",
      "name": "Commencement date",
      "field_type": "ftdate",
      "value": "2019-02-06"
    },
    {
      "code": "attr3",
      "name": "Date of the next call",
      "field_type": "ftdatetime",
      "value": "2019-02-21T14:00:00.000+03:00"
    },
    {
      "code": "attr4",
      "name": "VIP Service",
      "field_type": "ftcheckbox",
      "value": true
    },
    {
      "code": "attr5",
      "name": "Type of activity",
      "field_type": "ftselect",
      "value": "Software"
    },
    {
      "code": "attr6",
      "name": "Types of premises",
      "field_type": "ftmultiselect",
      "value": [
        "Head office",
        "Recreation area"
      ]
    }
  ],
  "schedule": {
    "id": 1,
    "name": "On weekdays, 9 a.m. to 6 p.m."
  },
  "observers": [
    {
      "id": 5,
      "name": "Andrei Russo"
    },
    {
      "id": 12,
      "name": "Alix Mckay"
    }
  ],
  "observer_groups": [
    {
      "id": 23,
      "name": "Mechanics"
    },
    {
      "id": 3,
      "name": "Drivers"
    }
  ],
  "attachments": [
    {
      "attachment_file_name": "file.jpg",
      "description": "Description",
      "is_public": true,
      "id": 575
    }
  ],
  "agreements": [
    {
      "id": 2,
      "title": "Important Contract"
    }
  ]
}

Warehouses ¶

Obtaining a list of warehouses

GET`/api/v1/warehouses{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
external_id	string	optional	External ID
page	associative array	optional	Associative array of parameters for a per-page display of the warehouse list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the warehouse starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the warehouse id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the warehouse’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the warehouse’s lowest id. Example: page[direction]=forward

Restriction of access rights

The list of warehouses will be provided only if the key-linked agent has access to a warehouse list in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 warehouses created will be returned.

An example of a query with the warehouse list per-page display parameters

https://<account>.okdesk.com/api/v1/warehouses?
  api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/warehouses?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 101,
    "name": "Second warehouse",
    "active": true,
    "external_id": "112233",
    "assignee_ids": [
      1,
      2
    ],
    "observer_ids": []
  },
  {
    "id": 100,
    "name": "First warehouse",
    "active": false,
    "external_id": null,
    "assignee_ids": [],
    "observer_ids": [
      1,
      2
    ]
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Warehouse info

GET`/api/v1/warehouses/{warehouse_id}{?api_token}`

Restriction of access rights

This method is not available for contact-associated keys.
This method is only available for keys associated with agents who have access to actions “Access to the Warehouses section”, “View warehouse in the list”

An example of a query:

https://<account>.okdesk.com/api/v1/warehouses/100?api_token=3e9a214215f493c4

URI example

GET https://<account>.okdesk.com/api/v1/warehouses/100?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
warehouse_id: integer (required) Example: 100
Warehouse ID.

Response 200

HideShow

Obtaining a list of balances

GET`/api/v1/material_assets/remainders{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
item_types	array of string	optional	Nomenclature type. Acceptable values: product, material.
page	associative array	optional	Associative array of parameters for a per-page display of the balance list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the nomenclature item starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the nomenclature item id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the nomenclature item’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the nomenclature item’s lowest id. Example: page[direction]=forward

Restriction of access rights

The list of balance will be provided only if the key-linked agent has access to a “Access to the Warehouses section” and “Viewing common balances” in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 balance created will be returned.

An example of a query with the balance list per-page display parameters

https://<account>.okdesk.com/api/v1/material_assets/remainders?
  api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/material_assets/remainders?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 101,
    "code": "item_code2",
    "name": "Nail",
    "active": true,
    "item_type": "product",
    "unit": "kg.",
    "vendor_code": "",
    "quantity": 1.5
  },
  {
    "id": 100,
    "code": "item_code1",
    "name": "Screw",
    "active": true,
    "item_type": "product",
    "unit": "kg.",
    "vendor_code": "",
    "quantity": 2.5
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Obtaining a list of warehouse balances

GET`/api/v1/warehouses/{warehouse_id}/remainders{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
page	associative array	optional	Associative array of parameters for a per-page display of the balance list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the nomenclature item starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the nomenclature item id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the nomenclature item’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the nomenclature item’s lowest id. Example: page[direction]=forward

Restriction of access rights

The list of warehouse balance will be provided only if the key-linked agent has access to a “Access to the Warehouses section” and “View warehouse card” in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 balance created will be returned.

An example of a query with the balance list per-page display parameters

https://<account>.okdesk.ru/api/v1/warehouses/100/remainders?
  api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/warehouses/100/remainders?api_token=3e9a214215f493c4

URI parameters

HideShow

warehouse_id: integer (required) Example: 100
Warehouse ID.
api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 101,
    "code": "item_code2",
    "name": "Nail",
    "active": true,
    "item_type": "product",
    "unit": "kg.",
    "vendor_code": "",
    "quantity": 1.5
  },
  {
    "id": 100,
    "code": "item_code1",
    "name": "Screw",
    "active": true,
    "item_type": "product",
    "unit": "kg.",
    "vendor_code": "",
    "quantity": 2.5
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Creating an inventory record

POST`/api/v1/material_assets/documents{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
doc_type	string	required	Document type. Valid values: posting, writing_off, moving
from_warehouse_id	integer	mandatory for documents with the write-off and transfer type	ID of the warehouse, from which the items will be written-off or transferred
to_warehouse_id	integer	mandatory for documents with the recognition and transfer type	ID of the warehouse, to which the items will be received or transferred
external_doc	string	optional	External document
accounted_at	string	optional	Document recording date

Restriction of access rights

An inventory record will be created only if a key-linked agent has access to the Warehouses section and rights to view the warehouse card, create and edit an inventory record in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

URI example

POST https://<account>.okdesk.com/api/v1/material_assets/documents?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 22,
  "accounted_at": "2023-01-12",
  "created_at": "2023-06-23T17:53:00.242+03:00",
  "external_doc": "1475823",
  "number": "000022",
  "doc_type": {
    "code": "writing_off",
    "name": "Writing-off"
  },
  "status": {
    "code": "drafted",
    "name": "Draft"
  },
  "author_id": 1,
  "from_warehouse": {
    "id": 11,
    "name": "Warehouse №11"
  },
  "to_warehouse": null
}

Retrieve the document list

GET`/api/v1/material_assets/documents{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
doc_types	array of string	optional	Array of document types. Valid values: posting, writing_off, moving. Example: doc_types[]=posting&doc_types[]=moving
statuses	array of string	optional	Array of document statuses. Valid values: drafted, waiting_for_approve, waiting_for_receive, accounted. Example: statuses[]=drafted&statuses[]=accounted
from_warehouses	array of integer	optional	Array of ID of warehouses, from which the items were written-off or transferred (From stock). Example: from_warehouses[]=1&from_warehouses[]=2
to_warehouses	array of integer	optional	Array of ID warehouses, to which the items were received or transferred (To stock). Example: to_warehouses[]=1&to_warehouses[]=2
external_doc	string	optional	External document. Example: external_doc=External
page	associative array	optional	Associative array of parameters for a per-page display of the document list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the inventory record starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the inventory record id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the inventory record’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the inventory record’s lowest id. Example: page[direction]=forward

Restriction of access rights

The list of inventory records will be retrieved only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

An example of a query with the document list per-page display parameters::

https://<account>.okdesk.com/api/v1/material_assets/documents?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/material_assets/documents?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 22,
    "accounted_at": "2023-01-12",
    "created_at": "2023-06-23T17:53:00.242+03:00",
    "external_doc": "1475823",
    "number": "000022",
    "doc_type": {
      "code": "writing_off",
      "name": "Writing-off"
    },
    "status": {
      "code": "drafted",
      "name": "Draft"
    },
    "author_id": 1,
    "from_warehouse": {
      "id": 11,
      "name": "Warehouse №11"
    },
    "to_warehouse": null
  }
]

Change status of inventory record

PATCH`/api/v1/material_assets/documents/{document_id}/statuses{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
code	string	required	Record status code. Valid values: drafted, waiting_for_approve, waiting_for_receive, accounted

Restriction of access rights

An inventory record status will be changed only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card. To change the “Draft” status to the “Approval” status, the right “Create, edit an inventory record” shall be checked. To change the “Approval” status to “Recorded”, “Pending acceptance” or “Draft”, the right “Change status of inventory record” shall be checked. To change the status “Recorded” to “Draft”, the right “Cancel recorded documents” shall be checked. This method is not available for keys linked to contact persons.

URI example

PATCH https://<account>.okdesk.com/api/v1/material_assets/documents/12/statuses?api_token=3e9a214215f493c4

URI parameters

HideShow

document_id: integer (required) Example: 12
Inventory record ID.
api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 22,
  "accounted_at": "2023-01-12",
  "created_at": "2023-06-23T17:53:00.242+03:00",
  "external_doc": "1475823",
  "number": "000022",
  "doc_type": {
    "code": "writing_off",
    "name": "Writing-off"
  },
  "status": {
    "code": "waiting_for_approve",
    "name": "Approval"
  },
  "author_id": 1,
  "from_warehouse": {
    "id": 11,
    "name": "Warehouse №11"
  },
  "to_warehouse": null
}

Retrieve inventory items in the inventory record

GET`/api/v1/material_assets/documents/{document_id}/items{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
page	associative array	optional	Associative array of parameters for a per-page display of the inventory items (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the inventory item starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the inventory item id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the inventory item’s largest id. forward returns item with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the inventory item’s lowest id. Example: page[direction]=forward

Restriction of access rights

The list of inventory items in the inventory record will be retrieved only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

An example of a query with the inventory item per-page display parameters

https://<account>.okdesk.com/api/v1/material_assets/documents/5/items?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/material_assets/documents/12/items?api_token=3e9a214215f493c4

URI parameters

HideShow

document_id: integer (required) Example: 12
Inventory record ID.
api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 4,
    "nomenclature_item_id": 5,
    "quantity": "2.0",
    "code": "item_code2",
    "name": "Nail",
    "vendor_code": "",
    "item_type": "product",
    "unit": "kg."
  },
  {
    "id": 5,
    "nomenclature_item_id": 6,
    "quantity": "1.5",
    "code": "item_code1",
    "name": "Screw",
    "vendor_code": "",
    "item_type": "product",
    "unit": "kg."
  }
]

Create inventory item in the inventory record

POST`/api/v1/material_assets/documents/{document_id}/items{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
nomenclature_item_id	integer	required	Nomenclature ID
quantity	float	required	Quantity

Restriction of access rights

The inventory item will be created in the inventory record only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card, create and edit the inventory record in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

URI example

POST https://<account>.okdesk.com/api/v1/material_assets/documents/12/items?api_token=3e9a214215f493c4

URI parameters

HideShow

document_id: integer (required) Example: 12
Inventory record ID.
api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 6,
  "nomenclature_item_id": 6,
  "quantity": "3.2",
  "code": "item_code1",
  "name": "Screw",
  "vendor_code": "",
  "item_type": "product",
  "unit": "kg."
}

Remove inventory item from the inventory record

DELETE`/api/v1/material_assets/documents/{document_id}/items/{item_id}{?api_token}`

Restriction of access rights

The inventory item will be removed from the inventory record only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card, create and edit the inventory record in accordance with the settings of access rights. This method is not available for keys linked to contact persons.

URI example

DELETE https://<account>.okdesk.com/api/v1/material_assets/documents/12/items/6?api_token=3e9a214215f493c4

URI parameters

HideShow

document_id: integer (required) Example: 12
Inventory record ID.
item_id: integer (required) Example: 6
Inventory item ID.
api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Integration with telephone service ¶

Transfer of information about the incoming call

POST`/api/v1/telephony/messages{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
telephony_numbers	array of integer	required	Extensions of employees, to which the call was transferred.
search_numbers_count	integer	required	The number of last digits of the caller’s number to find a match.
phone	string	required	The caller’s number.

Restriction of access rights

Data access is available without limitation only for keys associated with admin users (the “Administrator” role).

URI example

POST https://<account>.okdesk.com/api/v1/telephony/messages?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Response 200

HideShow

Making an entry about the phone call

POST`/api/v1/phone_calls{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
call_id	string	required	Call ID in the external system
started_at	string	required	Call start date/time
finished_at	string	required	Call termination date/time
duration	integer	required	Call duration (in seconds)
direction	integer	required	Call direction (1 for outgoing and 0 for incoming)
receiver_phone	string	required	Receiving number
source_phone	string	required	Caller’s number
search_numbers_count	integer	required	Number of the last digits of the outside party’s number to find a match in the client database
file_url	string	optional	Link to download a file with a recording of a phone call
issue_id	integer	optional	Call ticket id

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

URI example

POST https://<account>.okdesk.com/api/v1/phone_calls?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "phone_call": {
    "call_id": "test-123",
    "started_at": "2019-02-24 09:16",
    "finished_at": "2019-02-24 09:17",
    "duration": 60,
    "direction": 1,
    "source_phone": "811111111111",
    "receiver_phone": "82222222222",
    "search_numbers_count": 10,
    "file_url": "https://test.com/file.mp3",
    "issue_id": 1
  }
}

Response 201

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "phone_call": {
    "started_at": "2019-02-24 09:17",
    "finished_at": "2019-02-24 09:16",
    "duration": 60,
    "direction": 3,
    "source_phone": "811111111111",
    "receiver_phone": "82222222222",
    "search_numbers_count": -1,
    "file_url": "https://test.com/file.mp3",
    "issue_id": 1
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
    "errors": {
        "search_numbers_count": [
            "must be greater than 0"
        ],
        "call_id": [
            "is missing"
        ],
        "direction": [
            "must be one of: 0, 1"
        ],
        "compare_dates": [
            "End time of phone call must be greater than start time"
        ],
    }
}

Price list ¶

Obtaining lists by parameters

GET`/api/v1/price_lists{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
page	associative array	optional	Associative array of parameters for a per-page display of the price list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.

An example of a query with the price list lines per-page display parameters:

https://<account>.okdesk.com/api/v1/price_lists?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/price_lists?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 101,
    "name": "Price list of maintenance",
    "allow_without_category": false,
    "allow_without_company": false,
    "inverted_companies": false,
    "company_category_codes": [
      "partner",
      "client",
      "vipclient"
    ],
    "company_ids": [
      441,
      41
    ]
  },
  {
    "id": 100,
    "name": "General services, works and materials price list of the company",
    "allow_without_category": false,
    "allow_without_company": false,
    "inverted_companies": false,
    "company_category_codes": [],
    "company_ids": []
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Obtaining list line by parameters

GET`/api/v1/nomenclature/price_lists/{price_list_id}/services{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
search_string	string	optional	Target substring in nomenclature item name, description, item number.
item_types	array of string	optional	Nomenclature type. Acceptable values: service, product, material, work.
group_id	string	optional	Nomenclature item group ID (set the value “0” to the parameter to show nomenclature items without group).
page	associative array	optional	Associative array of parameters for a per-page display of the price list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace

An example of a query with the price list lines per-page display parameters:

https://<account>.okdesk.com/api/v1/nomenclature/price_lists/153/services?
  api_token=3e9a214215f493c4&item_types[]=service&item_types[]=work&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/nomenclature/price_lists/154/services?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
price_list_id: integer (required) Example: 154
Price list ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "nomenclature_item_id": 1,
    "code": "timerateservice",
    "name": "Pay per time services",
    "type": "service",
    "group": {
      "id": 1,
      "code": "group_code",
      "name": "Services"
    },
    "unit": "man-hour",
    "vendor_code": "",
    "price": 1000,
    "nds": 0,
    "visible": true,
    "description": "Different billed pay per hour services"
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "item_types": {
      "0": [
        "must be one of: service, product, material, work"
      ]
    },
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Price list line adding method

POST`/api/v1/nomenclature/price_lists/{price_list_id}/services{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
nomenclature_item_id	integer	required	Nomenclature item ID.
price	number	required	Price
nds	integer	required	VAT rate, %

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

URI example

POST https://<account>.okdesk.com/api/v1/nomenclature/price_lists/154/services?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
price_list_id: integer (required) Example: 154
Price list ID.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "nomenclature_item_id": 2,
  "code": "timerateservice",
  "name": "Pay per time services",
  "type": "service",
  "group": {
    "id": 1,
    "code": "group_code",
    "name": "Services"
  },
  "unit": "man-hour",
  "vendor_code": "",
  "price": 1000,
  "nds": 0,
  "visible": true,
  "description": "Different billed pay per hour services"
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Price list line editing method

PATCH`/api/v1/nomenclature/price_lists/{price_list_id}/services/{id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
price	number	optional	Price
nds	integer	optional	VAT rate, %
visible	boolean	optional	Activity status. Takes true or false value

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

URI example

PATCH https://<account>.okdesk.com/api/v1/nomenclature/price_lists/154/services/12?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
price_list_id: integer (required) Example: 154
Price list ID.
id: integer (required) Example: 12
Price list line ID.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "nomenclature_item_id": 2,
  "code": "timerateservice",
  "name": "Pay per time services",
  "type": "work",
  "group": {
    "id": 1,
    "code": "group_code",
    "name": "Services"
  },
  "unit": "man-hour",
  "vendor_code": "",
  "price": 2000,
  "nds": 5,
  "visible": true,
  "description": "Different billed pay per hour services"
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "price": [
      "must be a float or must be an integer"
    ],
    "nds": [
      "must be less than or equal to 100"
    ],
    "visible": [
      "must be a boolean"
    ]
  }
}

Obtaining available price list lines by parameters for ticket and user

GET`/api/v1/issues/{issue_id}/available_services{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
search_string	string	optional	Target substring in price list line name
item_types	array of string	optional	Nomenclature type. Acceptable values: service, product, material, work.
page	associative array	optional	Associative array of parameters for a per-page display of the price list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward

Restriction of access rights

This method is only available for keys associated with agents who have access to actions “View the ticket”, “Adding lines in the ticket quantities”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment types created will be returned.

An example of a query with the price list lines per-page display parameters

https://<account>.okdesk.com/api/v1/issues/1/available_services?
  api_token=3e9a214215f493c4&item_types[]=service&page[size]=3&page[from_id]=10&page[direction]=reverse&search_string=first

URI example

GET https://<account>.okdesk.com/api/v1/issues/763/available_services?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
issue_id: integer (required) Example: 763
Ticket ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "price_list_id": 3,
    "price_list_name": "Price list of maintenance",
    "id": 1,
    "nomenclature_item_id": 1,
    "code": "timerateservice",
    "name": "Pay per time services",
    "type": "work",
    "unit": "man-hour",
    "price": 2000,
    "nds": 5,
    "vendor_code": "",
    "description": "Different billed pay per hour services",
    "group": {
      "id": 1,
      "code": "group_code",
      "name": "Services"
    }
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Nomenclature ¶

Obtaining nomenclature groups

GET`/api/v1/nomenclature/groups{?api_token,search_string,code}`

Valid query parameters:

Name	Type	Mandatory	Description
search_string	string	optional	Target substring in nomenclature group name
code	string	optional	Nomenclature group code
page	associative array	optional	Associative array of parameters for a per-page display of the price list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace

An example of a query with the nomenclature groups per-page display parameters:

https://<account>.okdesk.com/api/v1/nomenclature/groups?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/nomenclature/groups?api_token=3e9a214215f493c4&search_string=Nested&code=group1

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
search_string: string (optional) Example: Nested
Target substring.
code: string (optional) Example: group1
Group code.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 101,
    "code": "group1",
    "name": "Nested group",
    "active": true,
    "group": {
      "id": 100,
      "code": "group2",
      "name": "Parent group"
    }
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Creation of nomenclature group

POST`/api/v1/nomenclature/groups{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
code	string	required	Group code
name	string	required	Group name
parent_id	integer	optional	Parent group ID

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

URI example

POST https://<account>.okdesk.com/api/v1/nomenclature/groups?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 100,
  "code": "group_code",
  "name": "Pay per time services",
  "active": true,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Parent group"
  }
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
    "errors": {
        "code": [
            "must be a string"
        ],
        "name": [
            "is missing"
        ],
        "parent_id": [
            "must be an integer"
        ],
    }
}

Obtaining nomenclature group by id

GET`/api/v1/nomenclature/groups/{id}{?api_token}`

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

URI example

GET https://<account>.okdesk.com/api/v1/nomenclature/groups/100?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 100
Group ID.

Response 200

HideShow

Editing of nomenclature group

PATCH`/api/v1/nomenclature/groups/{id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	optional	Group name
parent_id	integer	optional	Parent group ID
active	boolean	optional	Activity status. Takes true or false value

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

URI example

PATCH https://<account>.okdesk.com/api/v1/nomenclature/groups/100?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 100
Group ID.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 100,
  "code": "group_code",
  "name": "Pay per time services",
  "active": false,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Parent group"
  }
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Obtaining nomenclature items list

GET`/api/v1/nomenclature/items{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
search_string	string	optional	Target substring in nomenclature item name, code, item number
code	string	optional	Nomenclature item code
item_types	array of string	optional	Nomenclature type. Acceptable values: service, product, material, work. Example: item_types[]=work&item_types[]=service
group_id	integer	optional	Nomenclature item group ID (set the value “0” to the parameter to show nomenclature items without group)
page	associative array	optional	Associative array of parameters for a per-page display of the price list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace

An example of a query with the nomenclature items per-page display parameters:

https://<account>.okdesk.com/api/v1/nomenclature/items?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/nomenclature/items?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 101,
    "code": "item_code2",
    "name": "Pay per time services",
    "active": true,
    "item_type": "service",
    "unit": "man-hour",
    "vendor_code": null,
    "description": "",
    "group": {
      "id": 100,
      "code": "group2",
      "name": "Parent group"
    }
  },
  {
    "id": 100,
    "code": "item_code1",
    "name": "Delivery to the service center",
    "active": true,
    "item_type": "work",
    "unit": "field trip",
    "vendor_code": null,
    "description": "",
    "group": null
  }
]

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "page": {
      "size": [
        "must be less than or equal to 100"
      ],
      "direction": [
        "must be one of: reverse, forward"
      ],
      "from_id": [
        "must be an integer"
      ]
    }
  }
}

Creation of nomenclature item

POST`/api/v1/nomenclature/items{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
code	string	required	Nomenclature item code
name	string	required	Nomenclature item name
item_type	string	required	Nomenclature type. Acceptable values: service, product, material, work
unit	string	required	Nomenclature item unit of measure
description	string	optional	Nomenclature item description
group_id	integer	optional	Group ID
vendor_code	string	optional	Item number

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

URI example

POST https://<account>.okdesk.com/api/v1/nomenclature/items?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request with correct parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "nomenclature_item": {
    "code": "item_code1",
    "name": "Pay per time services",
    "item_type": "service",
    "unit": "man-hour",
    "group_id": 99
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 100,
  "code": "item_code1",
  "name": "Pay per time services",
  "active": true,
  "item_type": "service",
  "unit": "man-hour",
  "vendor_code": null,
  "description": null,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Parent group"
  }
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "code": [
      "must be a string"
    ],
    "name": [
      "is missing"
    ],
    "item_type": [
      "must be one of: service, product, material, work"
    ],
    "unit": [
      "is missing"
    ]
  }
}

Obtaining nomenclature item by id

GET`/api/v1/nomenclature/items/{id}{?api_token}`

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

URI example

GET https://<account>.okdesk.com/api/v1/nomenclature/items/100?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 100
Nomenclature item ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 100,
  "code": "item_code1",
  "name": "Pay per time services",
  "active": true,
  "item_type": "service",
  "unit": "man-hour",
  "vendor_code": null,
  "description": null,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Parent group"
  }
}

Editing of nomenclature item

PATCH`/api/v1/nomenclature/items/{id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	optional	Nomenclature item name
item_type	string	optional	Nomenclature type. Acceptable values: service, product, material, work
unit	string	optional	Nomenclature item unit of measure
description	string	optional	Nomenclature item description
group_id	integer	optional	Group ID
vendor_code	string	optional	Item number
active	boolean	optional	Activity status. Takes true or false value

Restriction of access rights

This method is only available for keys associated with agents who have access to action “Access to price-list management”.

URI example

PATCH https://<account>.okdesk.com/api/v1/nomenclature/items/100?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 100
Nomenclature item ID.

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 100,
  "code": "item_code1",
  "name": "Pay per time services",
  "active": false,
  "item_type": "service",
  "unit": "man-hour",
  "vendor_code": null,
  "description": null,
  "group": {
    "id": 99,
    "code": "parent_group_code",
    "name": "Parent group"
  }
}

Request with incorrect parameters

HideShow

Response 422

HideShow

Directories ¶

Obtaining a list of ticket types

GET`/api/v1/dictionaries/issues/types/{?api_token,parent_code}`

Please note

For contact-associated keys, internal-type tickets are not returned. Only limited information will be available:

Item ID;;
Item name;
Item code;
Item type (type - means ticket type, group - group);
Information about the presence of the “Available for selection by client” indicator in the ticket type;
Information about the presence of the “by default” indicator in the ticket type;
Embedded items;

URI example

GET https://<account>.okdesk.com/api/v1/dictionaries/issues/types/?api_token=3e9a214215f493c4&parent_code=service

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
parent_code: string (optional) Example: service
Parent group code.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 8,
    "name": "Service types",
    "code": "service",
    "type": "group",
    "children": [
      {
        "id": 2,
        "name": "Service",
        "code": "service",
        "default": true,
        "available_for_client": true,
        "inner": false,
        "type": "type"
      },
      {
        "id": 1,
        "name": "Incident",
        "code": "incident",
        "default": false,
        "available_for_client": false,
        "inner": false,
        "type": "type"
      }
    ]
  },
  {
    "id": 3,
    "name": "Inner",
    "code": "inner",
    "default": false,
    "available_for_client": false,
    "inner": true,
    "type": "type"
  }
]

Obtaining a list of ticket priorities

GET`/api/v1/issues/priorities/{?api_token}`

Please note

For contact-associated keys only limited information will be available:

Item name;
Item code;
Item order position;
Information about the presence of the “by default” indicator in the ticket type;
Item color;

URI example

GET https://<account>.okdesk.com/api/v1/issues/priorities/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "name": "Low",
    "code": "low",
    "position": 1,
    "default": true,
    "color": "#8e9eb3",
    "without_client": true,
    "company_without_category": false,
    "contact_without_company": false,
    "available_for_client": true,
    "company_category_codes": [
      "client"
    ],
    "company_ids": [
      45
    ],
    "employee_role_ids": [
      1
    ]
  },
  {
    "name": "Normal",
    "code": "normal",
    "position": 2,
    "default": false,
    "color": "#5cb85c",
    "without_client": true,
    "company_without_category": false,
    "contact_without_company": false,
    "available_for_client": true,
    "company_category_codes": [],
    "company_ids": [],
    "employee_role_ids": []
  },
  {
    "name": "High",
    "code": "high",
    "position": 3,
    "default": false,
    "color": "#ea2e49",
    "without_client": true,
    "company_without_category": false,
    "contact_without_company": false,
    "available_for_client": true,
    "company_category_codes": [],
    "company_ids": [],
    "employee_role_ids": []
  }
]

Obtaining a list of ticket statuses

GET`/api/v1/issues/statuses/{?api_token}`

Please note

For contact-associated keys, statuses with “Do not show status to client” option are not returned.

URI example

GET https://<account>.okdesk.com/api/v1/issues/statuses/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "code": "opened",
    "name": "Opened",
    "color": "#ff8522"
  },
  {
    "code": "delayed",
    "name": "Delayed",
    "color": "#ffc926"
  },
  {
    "code": "completed",
    "name": "Completed",
    "color": "#5cb85c"
  },
  {
    "code": "closed",
    "name": "Сlosed",
    "color": "#8e9eb3"
  }
]

Scheme of additional attributes of tickets

GET`/api/v1/issues/parameters/list{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
issue_type_codes	array	optional	Array of issue type codes

Please note

If an array of ticket type codes is passed, then additional attributes are returned that are available only for the transferred ticket types. If the user has transferred an ticket type that is hidden from him (for contact persons, types marked “Inner”, for agents, types hidden for all his roles in the “View the ticket” right setting), then the transferred code is ignored.

Restriction of access rights

For keys associated with contact, attributes with the value “Show in the ticket” of the “Visibility in the client portal” parameter are returned. The agent requires the presence of his role in the “May be displayed to employees having a role” parameter.

URI example

GET https://<account>.okdesk.com/api/v1/issues/parameters/list?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "code": "attr_string",
    "name": "String",
    "field_type": "ftstring",
    "required": false,
    "issue_type_codes": [
      "service",
      "inner",
      "incident"
    ]
  },
  {
    "code": "city",
    "name": "City",
    "field_type": "ftselect",
    "required": false,
    "issue_type_codes": [
      "service"
    ],
    "field_type_values": [
      "Tsaritsyn",
      "Simbirsk",
      "Petrograd"
    ]
  }
]

Scheme of additional attributes of ticket labor contribution

GET`/api/v1/time_entries/parameters{?api_token}`

Restriction of access rights

The method is available only for keys connected with agents.

URI example

GET https://<account>.okdesk.com/api/v1/time_entries/parameters?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "code": "attr_string",
    "name": "String",
    "field_type": "ftstring",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  },
  {
    "code": "attr_date",
    "name": "Date",
    "field_type": "ftdate",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  },
  {
    "code": "attr_datetime",
    "name": "Date/time",
    "field_type": "ftdatetime",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  },
  {
    "code": "attr_checkbox",
    "name": "Checkbox",
    "field_type": "ftcheckbox",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  },
  {
    "code": "attr_select",
    "name": "List item",
    "field_type": "ftselect",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true,
    "field_type_values": [
      "value_1",
      "value_2"
    ]
  },
  {
    "code": "attr_multiselect",
    "name": "List item set",
    "field_type": "ftmultiselect",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true,
    "field_type_values": [
      "value_1",
      "value_2"
    ]
  },
  {
    "code": "attr_text",
    "name": "Text",
    "field_type": "fttext",
    "required": false,
    "visible_on_time_entry_form": true,
    "visible_on_time_entries_list": true
  }
]

Scheme of additional attributes of equipment

GET`/api/v1/equipments/parameters{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
equipment_kind_codes	array	optional	Array of equipment kind codes Example: equipment_kind_codes[]=EG

Please note

If array of equipment codes is passed, then additional attributes are returned that are available only for the passed equipment kind.

Restriction of access rights

The method is available only for keys connected with agents. The agent requires the presence of his role in the “Available to the agents with the following roles” parameter.

URI example

GET https://<account>.okdesk.com/api/v1/equipments/parameters?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "code": "attr_string",
        "name": "String",
        "field_type": "ftstring",
        "required": false,
        "equipment_kind_codes": [
            "laptop"
        ]
    },
    {
        "code": "attr_date",
        "name": "Date",
        "field_type": "ftdate",
        "required": false,
        "equipment_kind_codes": [
            "laptop"
        ]
    },
    {
        "code": "attr_datetime",
        "name": "Date/time",
        "field_type": "ftdatetime",
        "required": false,
        "equipment_kind_codes": [
            "laptop"
        ]
    },
    {
        "code": "attr_checkbox",
        "name": "Checkbox",
        "field_type": "ftcheckbox",
        "required": false,
        "equipment_kind_codes": [
            "laptop"
        ]
    },
    {
        "code": "attr_select",
        "name": "List item",
        "field_type": "ftselect",
        "required": false,
        "equipment_kind_codes": [
            "laptop"
        ],
        "field_type_values": [
            "value_1",
            "value_2"
        ]
    },
    {
        "code": "attr_multiselect",
        "name": "List item set",
        "field_type": "ftmultiselect",
        "required": false,
        "equipment_kind_codes": [
            "laptop"
        ],
        "field_type_values": [
            "value_1",
            "value_2"
        ]
    },
    {
        "code": "attr_text",
        "name": "Text",
        "field_type": "fttext",
        "required": false,
    }
]

Obtaining a list of equipment types

GET`/api/v1/equipments/kinds/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
search_string	string	optional	Target substring in equipment type name or code
page	associative array	optional	Associative array of parameters for a per-page display of the equipment type list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the equipment type starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment type id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment type’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment type’s lowest id. Example: page[direction]=forward

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment types created will be returned.

An example of a query with the equipment type list per-page display parameters

https://<account>.okdesk.com/api/v1/equipments/kinds/?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward&search_string=special

URI example

GET https://<account>.okdesk.com/api/v1/equipments/kinds/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 5,
    "code": "005",
    "name": "somewhatspecialequipment",
    "description": "somewhat special equipment",
    "visible": true,
    "equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
    "parameters": [
      {
        "name": "Some_parameter 3",
        "field_type": "ftcheckbox"
      }
    ]
  },
  {
    "id": 8,
    "code": "008",
    "name": "specialequipment",
    "description": "special equipment",
    "visible": true,
    "equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
    "parameters": [
      {
        "name": "Some_parameter 2",
        "field_type": "ftcheckbox"
      }
    ]
  },
  {
    "id": 10,
    "code": "010",
    "name": "veryspecialequipment",
    "description": "very special equipment",
    "visible": true,
    "equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
    "parameters": [
      {
        "name": "Some_parameter 1",
        "field_type": "ftcheckbox"
      },
      {
        "name": "Some_parameter 2",
        "field_type": "ftcheckbox"
      }
    ]
  }
]

Creating equipment type

POST`/api/v1/equipments/kinds/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	required	Equipment type name
code	string	required	Equipment type code
description	string	optional	Equipment type description
parameter_codes	array of string	optional	Array of codes of linked extended attributes of equipment
equipment_name_format	string	optional	Equipment name template

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

URI example

POST https://<account>.okdesk.com/api/v1/equipments/kinds/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "equipment_kind": {
    "code": "sample_code",
    "name": "sample_name",
    "description": "sample_text",
    "equipment_name_format": "{{{SN}}} {{{INV}}}",
    "parameter_codes": [
      "001",
      "002"
    ]
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 57,
  "code": "sample_code",
  "name": "sample_name",
  "description": "sample_text",
  "visible": true,
  "equipment_name_format": "{{{SN}}} {{{INV}}}",
  "parameters": [
    {
      "name": "Parameter 1",
      "field_type": "ftstring"
    },
    {
      "name": "Parameter 2",
      "field_type": "ftstring"
    }
  ]
}

Editing of equipment type

PATCH`/api/v1/equipments/kinds/{kind_id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	optional	Equipment type name
description	string	optional	Equipment type description
parameter_codes	array of string	optional	Array of codes of linked extended attributes of equipment
visible	boolean	optional	Nesting indicator
equipment_name_format	string	optional	Equipment name template

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

URI example

PATCH https://<account>.okdesk.com/api/v1/equipments/kinds/57?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
kind_id: integer (required) Example: 57
Edited equipment type ID

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "equipment_kind": {
    "name": "changed_name",
    "description": "changed_text",
    "visible": false,
    "equipment_name_format": "{{{SN}}} {{{INV}}}",
    "parameter_codes": [
      "001",
      "003"
    ]
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 57,
  "code": "code",
  "name": "changed_name",
  "description": "changed_text",
  "visible": false,
  "equipment_name_format": "{{{SN}}} {{{INV}}}",
  "parameters": [
    {
      "name": "Parameter 1",
      "field_type": "ftstring"
    },
    {
      "name": "Parameter 3",
      "field_type": "ftcheckbox"
    }
  ]
}

Obtaining equipment manufacturers list

GET`/api/v1/equipments/manufacturers/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
search_string	string	optional	Target substring in equipment manufacturer name or code
page	associative array	optional	Associative array of parameters for a per-page display of the equipment manufacturer list (detailed description is available in the table below).

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the equipment manufacturer starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment manufacturer id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment manufacturer’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment manufacturer’s lowest id. Example: page[direction]=forward

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment manufacturers created will be returned.

An example of a query with the equipment manufacturer list per-page display parameters

https://<account>.okdesk.com/api/v1/equipments/manufacturers/?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=11&page[direction]=forward&search_string=special

URI example

GET https://<account>.okdesk.com/api/v1/equipments/manufacturers/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 5,
    "code": "005",
    "name": "manufacturer 5",
    "description": "somewhat special manufacturer",
    "visible": true
  },
  {
    "id": 8,
    "code": "008",
    "name": "manufacturer 8",
    "description": "special manufacturer",
    "visible": true
  },
  {
    "id": 10,
    "code": "010",
    "name": "manufacturer 10",
    "description": "very special manufacturer",
    "visible": true
  }
]

Creating equipment manufacturer

POST`/api/v1/equipments/manufacturers/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	required	Equipment manufacturer name
code	string	required	Equipment manufacturer code
description	string	optional	Equipment manufacturer description

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

URI example

POST https://<account>.okdesk.com/api/v1/equipments/manufacturers/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Response 200

HideShow

Editing equipment manufacturer

PATCH`/api/v1/equipments/manufacturers/{manufacturer_id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	optional	Equipment manufacturer name
description	string	optional	Equipment manufacturer description
visible	boolean	optional	Nesting indicator
equipment_name_format	string	optional	Equipment name template

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

URI example

PATCH https://<account>.okdesk.com/api/v1/equipments/manufacturers/57?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
manufacturer_id: integer (required) Example: 57
ID of editing equipment manufacturer

Request

HideShow

Response 200

HideShow

Obtaining list of equipment models

GET`/api/v1/equipments/models/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
search_string	string	optional	Target substring in equipment model name or code
page	associative array	optional	Associative array of parameters for a per-page display of the equipment model list (detailed description is available in the table below)…

Valid per-page display parameters:

Name	Type	Mandatory	Description
size	integer	optional	Number of returned entries. Cannot exceed 100. Example: page[size]=30
from_id	integer	optional	The ID of the equipment model starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment model id decreasing order. Example: page[from_id]=10
direction	string	optional	Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment model’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment model’s lowest id. Example: page[direction]=forward

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

Please note

This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment models created will be returned.

An example of a query with the equipment models list lines per-page display parameters:

https://<account>.okdesk.com/api/v1/equipments/models/?
  api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=forward&search_string=special

URI example

GET https://<account>.okdesk.com/api/v1/equipments/models/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 5,
    "code": "005",
    "name": "somewhatspecialequipment",
    "description": "somewhat special equipment",
    "visible": true,
    "equipment_kind": {
      "code": "002",
      "id": 2,
      "name": "sample_kind"
    },
    "equipment_manufacturer": {
      "code": "001",
      "id": 1,
      "name": "sample_manufacturer"
    }
  },
  {
    "id": 8,
    "code": "008",
    "name": "specialequipment",
    "description": "special equipment",
    "visible": true,
    "equipment_kind": {
      "code": "002",
      "id": 2,
      "name": "sample_kind"
    },
    "equipment_manufacturer": {
      "code": "002",
      "id": 2,
      "name": "second_sample_manufacturer"
    }
  },
  {
    "id": 10,
    "code": "010",
    "name": "veryspecialequipment",
    "description": "very special equipment",
    "visible": true,
    "equipment_kind": {
      "code": "003",
      "id": 4,
      "name": "another_sample_kind"
    },
    "equipment_manufacturer": {
      "code": "001",
      "id": 1,
      "name": "sample_manufacturer"
    }
  }
]

Creating equipment models

POST`/api/v1/equipments/models/{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	required	Equipment model name
code	string	required	Equipment model code
equipment_kind_id	integer	required	Equipment type ID
equipment_manufacturer_id	integer	required	Equipment manufacturer ID
description	string	optional	Equipment model description

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

URI example

POST https://<account>.okdesk.com/api/v1/equipments/models/?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "equipment_model": {
    "code": "model_code",
    "name": "model_name",
    "description": "sample",
    "equipment_kind_id": 1,
    "equipment_manufacturer_id": 1
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 57,
  "code": "model_code",
  "name": "model_name",
  "description": "sample",
  "visible": true,
  "equipment_kind": {
    "code": "001",
    "id": 1,
    "name": "sample_kind"
  },
  "equipment_manufacturer": {
    "code": "001",
    "id": 1,
    "name": "sample_manufacturer"
  }
}

Editing equipment model

PATCH`/api/v1/equipments/models/{model_id}{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
name	string	optional	Equipment model name
description	string	optional	Equipment model description
visible	boolean	optional	Nesting indicator
equipment_kind_id	integer	optional	Equipment type ID
equipment_manufacturer_id	integer	optional	Equipment manufacturer ID

Restriction of access rights

The method is only available for key associated with the user role “Administrator”.

URI example

PATCH https://<account>.okdesk.com/api/v1/equipments/models/57?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
model_id: integer (required) Example: 57
ID of editing equipment model

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "equipment_model": {
    "name": "changed_name",
    "description": "changed_text",
    "visible": false,
    "equipment_kind_id": 2,
    "equipment_manufacturer_id": 3
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 57,
  "code": "model code",
  "name": "changed_name",
  "description": "changed_text",
  "visible": false,
  "equipment_kind": {
    "code": "002",
    "id": 2,
    "name": "sample_kind"
  },
  "equipment_manufacturer": {
    "code": "003",
    "id": 3,
    "name": "some_manufacturer"
  }
}

Obtaining a list of time zones

GET`/api/v1/timezones{?api_token}`

Restriction of access rights

The method is only available for keys associated with the user role “Administrator”.

URI example

GET https://<account>.okdesk.com/api/v1/timezones?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "code": "Kaliningrad",
    "name": "Kaliningrad",
    "gmt": "+02:00"
  },
  {
    "code": "Moscow",
    "name": "Moscow",
    "gmt": "+03:00"
  },
  {
    "code": "Samara",
    "name": "Samara",
    "gmt": "+04:00"
  },
  {
    "code": "Irkutsk",
    "name": "Irkutsk",
    "gmt": "+08:00"
  }
]

Miscellaneous ¶

Creating a link to the login

POST`/api/v1/login_link{?api_token}`

Generation of a new one-time link to user authentication

Valid query parameters:

Name	Type	Mandatory	Description
user_login	string	optional	User login
user_type	string	optional	User type. Acceptable types: employee - agent, contact - contact person
user_id	integer	optional	User ID
expire_after	integer	optional	The link’s life in minutes. It will be set to 30 days, if its value is not defined.
one_time	boolean	optional	Link type (one-time / reusable). If the parameter is not passed, a one-time link for the login is created

Please note

If there is no user_login or one of the parameters user_type, user_id parameters, the link to login will be generated for the user associated with the key.

Restriction of access rights

The generation of links to user authentication is available without limitation only for keys associated with admin users (the “Administrator” role). In other cases, you can generate a link to authorization only for a user associated with the key.

URI example

POST https://<account>.okdesk.com/api/v1/login_link?api_token=3e9a214215f493c4

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.

Request

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "login_link": "http://<account>.okdesk.com/login?token=430379fd78be7c71623cad7590b8a23d",
  "user_id": 56,
  "user_type": "employee",
  "roles": [
    "Administrator"
  ],
  "user_first_name": "John",
  "user_last_name": "Kennedy",
  "user_patronymic": "Fitzgerald",
  "user_position": "Head of Technology",
  "user_email": "example@example.com",
  "user_custom_parameters": []
}

Companies ¶

Company search

GET/api/v1/companies/{?api_token,name,phone,id,crm_1c_id,search_string}

Restriction of access rights ¶

Please note ¶

URI example

Headers

Body

Creating a company

POST/api/v1/companies/{?api_token}

Valid query parameters: ¶

Restriction of access rights ¶

Please note ¶

URI example

Headers

Body

Headers

Body

Editing the company

PATCH/api/v1/companies/{company_id}{?api_token}

Valid query parameters: ¶

Restriction of access rights ¶

Please note ¶

URI example

Headers

Body

Headers

Body

Obtaining list by parameters

GET/api/v1/companies/list{?api_token}

Valid query parameters: ¶

Valid per-page display parameters: ¶

Restriction of access rights ¶

Please note ¶

Valid values of extended attributes: ¶

An example of a query with the company list per-page display parameters: ¶

URI example

Headers

Body

Headers

Body

Obtaining a file of a company

GET/api/v1/companies/{company_id}/attachments/{attachment_id}{?api_token}

Restriction of access rights ¶

Please note ¶

URI example

Headers

Body

Archiving companies

PATCH/api/v1/companies/{id}/activations{?api_token}

Valid query parameters: ¶

Restriction of access rights ¶

URI example

Headers

Body

Headers

Body

Employees ¶

Creating an agent

POST/api/v1/employees/{?api_token}

Valid query parameters: ¶

Restriction of access rights ¶

Please note ¶

URI example

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Editing an agent

PATCH/api/v1/employees/{employee_id}{?api_token}

Valid query parameters: ¶

Restriction of access rights ¶

Please note ¶

URI example

Headers

Body

GET`/api/v1/companies/{?api_token,name,phone,id,crm_1c_id,search_string}`

Restriction of access rights

Please note

POST`/api/v1/companies/{?api_token}`

Valid query parameters:

Restriction of access rights

Please note

PATCH`/api/v1/companies/{company_id}{?api_token}`

Valid query parameters:

Restriction of access rights

Please note

GET`/api/v1/companies/list{?api_token}`

Valid query parameters:

Valid per-page display parameters:

Restriction of access rights

Please note

Valid values of extended attributes:

An example of a query with the company list per-page display parameters:

GET`/api/v1/companies/{company_id}/attachments/{attachment_id}{?api_token}`

Restriction of access rights

Please note

PATCH`/api/v1/companies/{id}/activations{?api_token}`

Valid query parameters:

Restriction of access rights

POST`/api/v1/employees/{?api_token}`

Valid query parameters:

Restriction of access rights

Please note

PATCH`/api/v1/employees/{employee_id}{?api_token}`

Valid query parameters:

Restriction of access rights

Please note

PATCH`/api/v1/employees/{id}/activations{?api_token}`

Valid query parameters:

Restriction of access rights

GET`/api/v1/employees/roles{?api_token}`

Restriction of access rights

GET`/api/v1/employees/groups{?api_token}`

Restriction of access rights

GET`/api/v1/employees/routes/{?api_token}`

Valid query parameters:

Valid per-page display parameters:

Restriction of access rights

Please note

An example of a query with the agent coordinates per-page display parameters:

GET`/api/v1/employees/list/{?api_token}`

Valid per-page display parameters:

Valid per-page display parameters:

Restriction of access rights:

Please note

An example of a query with the agent list per-page display parameters:

GET`/api/v1/contacts/{?api_token,id,email,phone,search_string}`

Restriction of access rights

Please note

POST`/api/v1/contacts/{?api_token}`

Valid query parameters:

Please note

Restriction of access rights