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, internal ID, 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",
    "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"
        },
    "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
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,
    "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",
  "observers": [
    {
      "id": 2,
      "name": "Fred Bloggs"
    },
    {
      "id": 1,
      "name": "John Smith"
    }
  ],
  "contacts": [],
  "default_assignee": {
    "id": 1,
    "name": "John Smith"
  },
  "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
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,
    "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",
    "observers":
        [
            {
              "id": 2,
              "name": "Fred Bloggs"
            },
            {
              "id": 1,
              "name": "John Smith"
            }
        ],
    "contacts": [],
    "default_assignee":
        {
            "id": 1,
            "name": "John Smith"
        },
    "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

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

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",
  "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",
  "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",
    "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, phone or mobile phone number 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.

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": "Sally Housecoat",
  "position": "Manager",
  "email": "employee@okdesk.com",
  "phone": "+79459999999",
  "mobile_phone": "+79999999999",
  "comment": "Senior Manager is responsible for Strategic Planning",
  "cc_email": "employee@okdesk.com",
  "login": "egorov3020",
  "crm_1c_id": "67067c3349a8",
  "updated_at": "2019-09-30T15:12:09.095+03:00",
  "company_id": 1,
  "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
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 (access to reports), 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)
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",
    "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"
    ],
    "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": "Sally Housecoat",
  "position": "Manager",
  "email": "employee@okdesk.com",
  "phone": "+79459999999",
  "mobile_phone": "+79999999999",
  "comment": "Senior Manager is responsible for Strategic Planning",
  "company_id": 1,
  "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",
  "observers": [
    {
      "id": 2,
      "name": "Fred Bloggs"
    },
    {
      "id": 1,
      "name": "John Smith"
    }
  ],
  "access_level": [
    "access_to_reports"
  ],
  "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
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 (access to reports), 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)
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",
    "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,
  "first_name": "John",
  "last_name": "Doe",
  "patronymic": "Smith",
  "position": "Manager",
  "email": "ivanov@okdesk.com",
  "login": "ivanov",
  "phone": "+79452222222",
  "mobile_phone": "+73333333333",
  "company_id": 33,
  "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",
  "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,
  "first_name": "John",
  "last_name": "Doe",
  "patronymic": "Smith",
  "position": "Manager",
  "email": "ivanov@okdesk.com",
  "login": "ivanov",
  "phone": "+79452222222",
  "mobile_phone": "+73333333333",
  "company_id": 33,
  "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",
  "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,
    "first_name": "John",
    "last_name": "Doe",
    "patronymic": "Smith",
    "active": true,
    "email": "mail@johndoe.com",
    "phone": "+79876543210",
    "mobile_phone": "+71234567890",
    "updated_at": "2019-09-30T15:12:09.095+03:00",
    "company_id": 2,
    "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,
    "first_name": "Frank",
    "last_name": "Castle",
    "patronymic": "Rook",
    "active": true,
    "email": "mail@frankcastle.com",
    "phone": "+79876543211",
    "mobile_phone": "+71234567899",
    "updated_at": "2019-09-30T15:12:09.095+03:00",
    "company_id": 2,
    "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
    ],
    "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
  ],
  "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
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
    ],
    "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
  ],
  "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
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
  ],
  "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
}

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

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

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 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.
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,
  "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"
  },
  "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"
  },
  "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 list by parameters

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

Valid query parameters:

Name	Type	Mandatory	Description
assignee_ids	array of integer	optional	Array of ticket responsible agent IDs (set the value “0” to the parameter to show tickets without a responsible agent). Example: assignee_ids[]=1&assignee_ids[]=2
assignee_group_ids	array of integer	optional	Array of ticket responsible group IDs (set the value “0” to the parameter to show tickets without a responsible group). Example: assignee_group_ids[]=1&assignee_group_ids[]=2
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
agreement_ids	array of integer	optional	Array of contract IDs (set the value “0” to the parameter to show tickets without a contract). Example: agreement_ids[]=1&agreement_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
author_employee_ids	array of integer	optional	Array of ticket initiator IDs (set the value “0” to the parameter to show tickets without an initiator). Example: author_employee_ids[]=1 Combined with author_contact_ids parameter using OR rule
author_contact_ids	array of integer	optional	Array of ticket initiating contact IDs (set the value “0” to the parameter to show tickets without an initiator). Example: author_contact_ids[]=57 Combined with author_employee_ids parameter using OR rule
maintenance_entity_ids	array of integer	optional	Array of IDs of service aims that are associated with tickets. Example: maintenance_entity_ids[]=1
equipment_ids	array of integer	optional	An array of equipment ID associated with tickets (to display tickets that have no equipment attached, you must pass the value “0” to the parameter). Example: equipment_ids[]=4
status	array of string	optional	Array of Ticket status codes Example: status[]=opened&status[]=completed
status_not	array of string	optional	Array of Codes of ticket statuses that are forbidden for the ticket Example: status_not[]=opened&status_not[]=completed
opened	boolean	optional	Flag "Open tickets". If the field value is true, the tickets with statuses indicating “Tickets in this status are deemed completed” will not be fetched.
priority	array of string	optional	Array of Ticket priority codes Example: priority[]=high&priority[]=low
type	array of string	optional	Array of Ticket type codes Example: type[]=incident
rate	array of string	optional	Array of Ticket rating values (set the value “0” to the parameter to show tickets without a rating). Example: rate[]=bad&rate[]=normal&rate[]=good
created_since	string	optional	Date of ticket creation (From) Example: created_since=22-03-2016
created_until	string	optional	Date of ticket creation (Until) Example: created_until=22-06-2016
overdue	integer	optional	Flag “Tickets with deadline expired”. If the value in the field is 1, then only tikets with the deadline expired will be selected. If the value in the field is 0, then all tickets will be selected. Example: overdue=0
overdue_reaction	integer	optional	Flag “Tickets with response time exceeded”. If the value in the field is 1, then only tikets with the response time exceeded will be selected. If the value in the field is 0, then all tickets will be selected. Example: overdue_reaction=0
completed_since	string	optional	Date of ticket resolution (From) Example: completed_since=22-03-2018
completed_until	string	optional	Date of ticket resolution (Until) Example: completed_until=22-06-2018
updated_since	string	optional	Date of the last ticket update (From) Example: updated_since=03-12-2018
updated_until	string	optional	Date of the last ticket update (Until) Example: updated_until=03-12-2018
reacted_since	string	optional	Actual response time (From) Example: reacted_since=03-12-2018 15:30
reacted_until	string	optional	Actual response time (Until) Example: reacted_until=06-12-2018 18:00
deadline_since	string	optional	Planned resolution date (From) Example: deadline_since=03-12-2018 15:30
deadline_until	string	optional	Planned resolution date (Until) Example: deadline_until=06-12-2018 18:00
start_execution_since	string	optional	Scheduled for (From) Example: start_execution_since=05-07-2021 11:30
start_execution_until	string	optional	Scheduled for (Until) Example: start_execution_until=06-07-2021 00:00
planned_reaction_since	string	optional	Planned reaction time (From) Example: planned_reaction_since=05-07-2021 11:30
planned_reaction_until	string	optional	Planned reaction time (Until) Example: planned_reaction_until=06-07-2021 00:00
custom_parameters	associative array	optional	Associative array of Extended attribute code pairs: Value or set of values

Please note

You can find codes of ticket status, priority, and type in the corresponding “Settings” menu section of your account.

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 tickets related directly to the contact 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

URI example

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

URI parameters

HideShow

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

Response 200

HideShow

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
    "errors": [
        {
            "message": 'Incorrect assignee_ids data',
            "invalid_data": [
                -333,
                111
            ]
        },
        {
            "message": 'Incorrect status_codes data',
            "invalid_data": [
                "done"
            ]
        },
        {
            "message": 'Incorrect created_since data',
            "invalid_data": "33-29-2016"
        }
    ]
}

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

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": {
      "type": "service",
      "code": "timerateservice",
      "unit": "field trip"
    },
    "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": {
      "type": "service",
      "code": "timerateservice",
      "unit": "man-hour"
    },
    "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
code	string	required	Code of the quantities line from the price list
quantity	number	required	Quantity (non-negative number)
performer_id	integer	optional	Responsible agent ID
price_list_id	integer	optional	the price list 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 code* of the quantities line (code) 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

Headers

Content-Type: application/json

Body

{
  "issue_service": {
    "code": "service",
    "quantity": 1,
    "performer_id": 3,
    "comment": "Comment",
    "discount": 2,
    "total": 600,
    "price_list_id": 2
  }
}

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": {
    "type": "service",
    "code": "timerateservice",
    "unit": "field trip"
  },
  "price_list": {
    "id": 2,
    "name": "Field services"
  },
  "performer": {
    "id": 3,
    "name": "Max Mustermann"
  }
}

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "issue_service": {
    "code": "wrong_code",
    "performer_id": 103,
    "comment": "Comment",
    "discount": 2.1,
    "total": -600,
    "price_list_id": 2000
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "code": [
      "Price list row does not exist or is not active"
    ],
    "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"
    ],
    "price_list": [
      "The price list does not exist or is not active"
    ]
  }
}

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,
        "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,
        "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.
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"
        ],
        "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,
    "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,
    "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,
    "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"
            ]
          }
        ]
      }
    ]
  }
}

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,
        "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,
        "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,
        "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,
        "position": 2,
        "checked_by_user_id": null,
        "checked": false
    },
]

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

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

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

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

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,
    "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,
  "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,
  "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,
    "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
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,
    "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,
    "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
Ключ авторизации.
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,
    "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"
        }
    ]
}

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

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

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

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,
    "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,
    "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/price_lists/{price_list_id}/services{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
types	array of string	required	Array of price list sections. Acceptable values: service, work, product. Example: &types[]=work&types[]=service
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/153/services?
  api_token=3e9a214215f493c4&types[]=service&page[size]=3&page[from_id]=10&page[direction]=reverse

URI example

GET https://<account>.okdesk.com/api/v1/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.
types[]: array[string] (required) Example: 'work'
Array of price list sections.

Response 200

HideShow

Headers

Content-Type: application/json

Body

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

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "types": {
      "0": [
        "must be one of: service, work, product"
      ]
    },
    "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/price_lists/{price_list_id}/services{?api_token}`

Valid query parameters:

Name	Type	Mandatory	Description
code	string	required	Directory line code
name	string	required	Directory line name
type	string	required	Directory line section. Acceptable values: work, product, service
unit	string	required	Unit of measure
price	number	required	Price
nds	integer	required	VAT rate, %
visible	boolean	optional	Activity status. Takes true or false value
description	string	optional	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/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

Headers

Content-Type: application/json

Body

{
  "service": {
    "code": "timerateservice",
    "name": "Pay per time services",
    "type": "service",
    "unit": "man-hour",
    "price": 1000,
    "nds": 0,
    "description": "Different billed pay per hour services"
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

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

Request with incorrect parameters

HideShow

Headers

Content-Type: application/json

Body

{
  "service": {
    "code": "timerateservice",
    "type": "wrong",
    "unit": "man-hour",
    "price": "wrong",
    "nds": 0,
    "description": "Different billed pay per hour services"
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "name": [
      "is missing"
    ],
    "type": [
      "must be one of: service, work, product"
    ],
    "price": [
      "must be a float or must be an integer"
    ]
  }
}

Price list line editing method

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

Valid query parameters:

Name	Type	Mandatory	Description
name	string	optional	Directory line name
type	string	optional	Directory line section. Acceptable values: work, product, service
unit	string	optional	Unit of measure
price	number	optional	Price
nds	integer	optional	VAT rate, %
visible	boolean	optional	Activity status. Takes true or false value
description	string	optional	Description

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/price_lists/154/services/timerateservice?api_token=3e9a214215f493c4

URI parameters

HideShow

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

Request with correct parameters

HideShow

Response 200

HideShow

Headers

Content-Type: application/json

Body

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

Request with incorrect parameters

HideShow

Response 422

HideShow

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
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.ru/api/v1/issues/1/available_services?
  api_token=3e9a214215f493c4&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,
    "code": "timerateservice",
    "name": "Pay per time services",
    "type": "work",
    "unit": "man-hour",
    "price": 2000,
    "nds": 5,
    "description": "Different billed pay per hour 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"
      ]
    }
  }
}

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

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

[
  {
    "code": "low",
    "name": "Low",
    "position": 1,
    "default": true,
    "color": "#8e9eb3"
  },
  {
    "code": "normal",
    "name": "Normal",
    "position": 2,
    "default": false,
    "color": "#5cb85c"
  },
  {
    "code": "high",
    "name": "High",
    "position": 3,
    "default": false,
    "color": "#ea2e49"
  }
]

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

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,
    "parameters": [
      {
        "name": "Some_parameter 3",
        "field_type": "ftcheckbox"
      }
    ]
  },
  {
    "id": 8,
    "code": "008",
    "name": "specialequipment",
    "description": "special equipment",
    "visible": true,
    "parameters": [
      {
        "name": "Some_parameter 2",
        "field_type": "ftcheckbox"
      }
    ]
  },
  {
    "id": 10,
    "code": "010",
    "name": "veryspecialequipment",
    "description": "very special equipment",
    "visible": true,
    "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

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

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

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": []
}

Creating an API-key for a user

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

Generating a new API-key for a user

Valid query parameters:

Name	Type	Mandatory	Description
user_type	string	mandatory	User type (employee or contact)
id	integer	mandatory	User ID

Restriction of access rights

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

URI example

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

URI parameters

HideShow

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

Request

HideShow

Response 200

HideShow

Request

HideShow

Response 422

HideShow

Obtaining an API-key of a user

GET`/api/v1/api_key{?api_token}&user_type={user_type}&id={id}`

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/api_key?api_token=3e9a214215f493c4&user_type=employee&id=2

URI parameters

HideShow

api_token: string (required) Example: 3e9a214215f493c4
Authorization key.
id: integer (required) Example: 2
User internal ID
user_type: string (required) Example: employee
User type

Response 200

HideShow

Response 422

HideShow

Obtaining an API-key of a user by login and password

POST`/api/v1/users/sign_in`

Valid query parameters:

Name	Type	Mandatory	Description
login	string	required	User login (employee or contact)
password	string	required	Password

URI example

POST https://<account>.okdesk.com/api/v1/users/sign_in

Request with correct parameters

HideShow

Response 200

HideShow

Request with incorrect parameters

HideShow

Response 422

HideShow

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

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

Headers

Body

Headers

Body

Headers

Body

Agent activation

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

Valid query parameters: ¶

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

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

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

Valid query parameters:

Please note

Restriction of access rights