API Okdesk
This documentation describes the existing methods of Okdesk API.
Select method in the side menu.
All queries require api_token parameter (authorization key). The authorization key can be generated in the API section of your Okdesk account settings.
Companies ¶
Company search
GET/api/v1/companies/{?api_token,name,phone,id,crm_1c_id,search_string}
The search is carried out by the exact match of the name or additional name of the company, phone and internal ID, by the occurrence of a substring in the value of the object ID in 1C or substring
Restriction of access rights ¶
Search of the company will be completed only if the key-linked agent has access to the list of companies in accordance with the access rights settings. This method is not available for contact-associated keys.
Please note ¶
-
When transferring the search_string parameter, the other parameters are not considered
-
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace
URI example
GET https://<account>.okdesk.com/api/v1/companies/?api_token=3e9a214215f493c4&name=Okdesk&phone=+7(499)703-47-20&id=1040&crm_1c_id=35067c4b23a8&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- name
string(optional) Example: OkdeskName
- phone
string(optional) Example: +7(499)703-47-20Phone number
- id
integer(optional) Example: 1040Internal Company ID
- crm_1c_id
string(optional) Example: 35067c4b23a8Object ID in 1C
- search_string
string(optional) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1040,
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"crm_1c_id": "35067c4b23a8",
"active": true,
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions."
"observers":
[
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"contacts": [],
"default_assignee":
{
"id": 1,
"name": "John Smith"
},
"default_assignee_group":
{
"id": 1,
"name": "Monitoring Group",
"active": true,
"description": ""
},
"category":
{
"id": 3,
"code": "vipclient",
"name": "VIP-client",
"color": "#5cb85c"
},
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
],
"external_observers": [
{
"id": 5,
"name": "John Johnson"
},
{
"id": 6,
"name": "Anna Davis"
}
]
}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 |
| string | optional | Company contact e-mail address | |
| phone | string | optional | Company contact phone |
| address | string | optional | Company address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc. |
| coordinates | array of float | optional | Company coordinates |
| comment | string | optional | Additional company info |
| observer_ids | array of integer | optional | User ID array for company viewers |
| default_assignee_id | integer | optional | ID of the responsible agent assigned for this company by default |
| default_assignee_group_id | integer | optional | ID of the responsible agent group |
| category_code | string | optional | Client category code |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Company extended attributes |
Restriction of access rights ¶
Creation of a company is available to agents in accordance with the settings of access rights. This method is not available for contact-associated keys.
Please note ¶
The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude).
URI example
POST https://<account>.okdesk.com/api/v1/companies/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"company": {
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
"observer_ids": [
1,
2
],
"default_assignee_id": 1,
"default_assignee_group_id": 1,
"category_code": "client",
"crm_1c_id": "67067c3a29a8",
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1040,
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
"crm_1c_id": "67067c3a29a8",
"active": true,
"observers": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"contacts": [],
"default_assignee": {
"id": 1,
"name": "John Smith"
},
"default_assignee_group": {
"id": 1,
"name": "Monitoring Group",
"active": true,
"description": ""
},
"category": {
"id": 2,
"code": "client",
"name": "Client",
"color": "#5cb85c"
},
"attachments": [],
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-15"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
],
"external_observers": []
}Editing the company
PATCH/api/v1/companies/{?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 |
| string | optional | Company contact e-mail address | |
| phone | string | optional | Company contact phone |
| address | string | optional | Company address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc. |
| coordinates | array of float | optional | Company coordinates |
| comment | string | optional | Additional company info |
| observer_ids | array of integer | optional | User ID array for company viewers |
| default_assignee_id | integer | optional | ID of the responsible agent assigned for this company by default |
| default_assignee_group_id | integer | optional | ID of the responsible agent group |
| category_code | string | optional | Client category code |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Company extended attributes |
Restriction of access rights ¶
Editing of the company will be completed only if the key-linked agent has the rights to view the company and edit the company attributes in accordance with the access rights settings. This method is not available for contact-associated keys.
Please note ¶
The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude).
URI example
PATCH https://<account>.okdesk.com/api/v1/companies/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- company_id
integer(required) Example: 4Company ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"company": {
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions.",
"observer_ids": [
1,
2
],
"default_assignee_id": 1,
"default_assignee_group_id": 1,
"category_code": "vipclient",
"crm_1c_id": "67067c3a29a8",
"custom_parameters": {
"code2": "2019-02-22"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1040,
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions."
"crm_1c_id": "67067c3a29a8",
"active": true,
"observers":
[
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"contacts": [],
"default_assignee":
{
"id": 1,
"name": "John Smith"
},
"default_assignee_group":
{
"id": 1,
"name": "Monitoring Group",
"active": true,
"description": ""
},
"category":
{
"id": 2,
"code": "vipclient",
"name": "VIP-client",
"color": "#5cb85c"
},
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-22"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
],
"external_observers": [
{
"id": 5,
"name": "John Johnson"
},
{
"id": 6,
"name": "Anna Davis"
}
]
}Obtaining list by parameters
GET/api/v1/companies/list{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| category_ids | array of integer | optional | Array of company category IDs (set the value “0” to the parameter to show companies without category). Example: category_ids[]=1 |
| default_assignee_ids | array of integer | optional | Array of company responsible agent IDs (set the value “0” to the parameter to show companies without a responsible agent). Example: default_assignee_ids[]=1 |
| default_assignee_group_ids | array of integer | optional | Array of company responsible group IDs (set the value “0” to the parameter to show companies without a responsible group). Example: default_assignee_group_ids[]=1 |
| observer_ids | array of integer | optional | Array of company viewer IDs (set the value “0” to the parameter to show companies without viewers). Example: observer_ids[]=1 |
| observer_group_ids | array of integer | optional | Array of company viewer group IDs (set the value “0” to the parameter to show companies without viewer groups). Example: observer_group_ids[]=1 |
| created_since | string | optional | The date the company was created in the account’s time zone (From) Example: created_since=2019-05-25 |
| created_until | string | optional | The date the company was created in the account’s time zone (Until) Example: created_until=2019-05-25 |
| custom_parameters | associative array | optional | Associative array of Extended attribute code pairs: Value or set of values |
| name | string | optional | Name Example: name=Okdesk |
| additional_name | string | optional | Additional company name Example: additional_name=Help Desk system for service companies |
| crm_1c_id | string | optional | Object ID in 1C Example: crm_1c_id=35067c4b23a8 |
| page | associative array | optional | Associative array of parameters for a per-page display of the company list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the company starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the company id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the company’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the company’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
Retrieving of the list of companies will be completed only if the key-linked agent has access to the list of companies in accordance with the access rights settings. This method is not available for contact-associated keys.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 companies created will be returned.
Valid values of extended attributes: ¶
| Parameter type | Type | Description |
|---|---|---|
| Date | string | There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12 |
| Date/time | string | There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12 |
| Checkbox | string | Two values – true and false – are available. Example: custom_parameters[checkbox_code]=true |
| List item | array of string | An array of list values. Example: custom_parameters[list_code][]=list_value |
| List item set | array of string | An array of list values. Example: custom_parameters[list_code][]=list_value |
| String | string | String type value (pass #null to return companies with empty attribute value). Example: custom_parameters[string_code]=string_value |
An example of a query with the company list per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/companies/list?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/companies/list?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 22,
"name": "Mom and Pop",
"additional_name": "Help Desk system for service companies",
"active": true,
"category": null,
"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": 10,
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"category": {
"id": 1,
"code": "vipclient",
"name": "VIP client",
"color": "#FF0000"
},
"active": true,
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2021-02-22"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
]
},
{
"id": 12,
"name": "Acme Ltd.",
"additional_name": "Help Desk system for service companies",
"active": true,
"category": {
"id": 2,
"code": "partner",
"name": "Partner",
"color": "#ffee00"
},
"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": 132,
"name": "VT",
"additional_name": "Virtual Technology",
"category": {
"id": 1,
"code": "client",
"name": "Client",
"color": "#00ff00"
},
"active": true,
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2024-02-22"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": false
}
]
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- company_id
integer(required) Example: 166company ID.
- attachment_id
integer(required) Example: 22File ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 22,
"attachment_file_name": "image.jpg",
"description": "",
"attachment_file_size": 7955,
"is_public": true,
"created_at": "2019-10-29T17:31:30.675+03:00",
"attachment_url": "https://static.okdesk.com/attachments/attachments/000/000/150/original/hqdefault.jpg"
}Archiving companies
PATCH/api/v1/companies/{id}/activations{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| active | boolean | required | Company activation status |
Restriction of access rights ¶
Company archiving is available to agents in accordance with the settings of access rights.
URI example
PATCH https://<account>.okdesk.com/api/v1/companies/1040/activations?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 1040company ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"active": true
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1040,
"name": "Okdesk",
"additional_name": "Help Desk system for service companies",
"site": "http://okdesk.com",
"email": "info@okdesk.com",
"phone": "+7(499)703-47-20",
"address": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
],
"comment": "Okdesk is a user-friendly cloud-based Help Desk system for automating support team processes in small and medium-sized service companies. It allows you to keep records of trouble tickets, customers and all interactions with them, service level agreements (SLA), contracts, their term of validity and payment conditions."
"crm_1c_id": "67067c3a29a8",
"active": true,
"observers":
[
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"contacts": [],
"default_assignee":
{
"id": 1,
"name": "John Smith"
},
"default_assignee_group":
{
"id": 1,
"name": "Monitoring Group",
"active": true,
"description": ""
},
"category":
{
"id": 2,
"code": "vipclient",
"name": "VIP-client",
"color": "#5cb85c"
},
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-22"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
],
"external_observers": [
{
"id": 5,
"name": "John Johnson"
},
{
"id": 6,
"name": "Anna Davis"
}
]
}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 |
| 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 |
| custom_parameters | associative array | optional | Agent extended attributes |
Restriction of access rights ¶
Employee creation is available to employees in accordance with access rights settings. Specifying an employee group is only possible if the employee associated with the key has the right to edit the group. This method is not available for keys associated with contacts.
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: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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",
"custom_parameters": {
"code2": "2024-01-25"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": "10",
"last_name": "Meatball",
"first_name": "Joe",
"patronymic": "Smith",
"position": "Manager",
"active": false,
"email": "employee@okdesk.com",
"login": "joe_manager",
"phone": "+79459999999",
"telephony_number": "0321",
"mobile_last_seen": null,
"last_seen": null,
"comment": "Senior Manager is responsible for Strategic Planning",
"groups": [
{
"id": 2,
"name": "Quality control department"
},
{
"id": 3,
"name": "Sales department"
}
],
"roles": [
{
"id": 1,
"name": "Admin"
}
],
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2024-01-25"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"employee": {
"last_name": "Meatball",
"email": "employee",
"login": 123,
"password": "12345678",
"role_ids": [
1
],
"phone": "+79459999999"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"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 |
| 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 |
| custom_parameters | associative array | optional | Agent extended attributes |
Restriction of access rights ¶
The employee edit will be performed only if the employee associated with the key has the right to edit the passed parameter, specifically the right to change employee parameters, the right to change employee roles, the right to change employee login, the right to change employee password, and the right to edit the group.
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: 10Agent ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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",
"custom_parameters": {
"code2": "2024-01-25"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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"
}
],
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2024-01-25"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"employee": {
"email": "employee",
"login": 123
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"email": [
"has invalid format"
],
"login": [
"must be a string"
]
}
}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 ¶
Employee activation is available to employees in accordance with access rights settings.
URI example
PATCH https://<account>.okdesk.com/api/v1/employees/10/activations?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 10agent ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"active": true
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 10,
"last_name": "Meatball",
"first_name": "Joe",
"patronymic": "Smith",
"position": "Manager",
"active": false,
"email": "employee@okdesk.com",
"login": "joe_manager",
"phone": "+79459999999",
"telephony_number": "0321",
"mobile_last_seen": null,
"last_seen": null,
"comment": "Senior Manager is responsible for Strategic Planning",
"groups": [
{
"id": 4,
"name": "Analytics department"
}
],
"roles": [
{
"id": 1,
"name": "Admin"
},
{
"id": 2,
"name": "Manager"
}
],
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2024-01-25"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"active": 'wrong'
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"active": [
"must be boolean"
]
}
}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: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"name": "Administrator"
},
{
"id": 2,
"name": "Lead expert"
},
{
"id": 3,
"name": "Expert"
}
]Receiving agents groups
GET/api/v1/employees/groups{?api_token}
Restriction of access rights ¶
Retrieving a list of groups will be executed only if the employee associated with the key has the right to view the group in accordance with access rights settings.
URI example
GET https://<account>.okdesk.com/api/v1/employees/groups?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"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 ¶
Retrieving an employee route will be executed only if the employee associated with the key has the right to display the employee on the map in accordance with access rights settings.
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.com/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:00URI example
GET https://<account>.okdesk.com/api/v1/employees/routes/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"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: ¶
Retrieving a list of employees will be executed only if the employee associated with the key has the right to view the list of employees and the right to view the employee card in accordance with access rights settings. This method is not available for keys associated with contacts.
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]=reverseURI example
GET https://<account>.okdesk.com/api/v1/employees/list/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": "10",
"last_name": "Meatball",
"first_name": "Joe",
"patronymic": "Smith",
"position": "Manager",
"active": false,
"email": "employee@okdesk.com",
"login": "joe_manager",
"phone": "+79459999999",
"telephony_number": "0321",
"mobile_last_seen": "2023-11-30T15:11:09.095+03:00",
"last_seen": "2023-11-30T15:08:09.095+03:00",
"comment": "Senior Manager is responsible for Strategic Planning",
"groups": [
{
"id": 4,
"name": "Analytics department"
}
],
"roles": [
{
"id": 1,
"name": "Admin"
}
],
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2024-01-25"
}
]
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"active": [
"must be one of: true, false"
],
"role_ids": {
0: [
"must be an integer"
],
}
}
}Contacts ¶
Contact search
GET/api/v1/contacts/{?api_token,id,email,phone,search_string}
The search is carried out by the exact match of the contact’s email or additional email address, contact’s Telegram account, by matching the last N digits of the contact’s phone or mobile phone, or substring
Restriction of access rights ¶
Search of the contact will be completed only if the key-linked agent has access to the contacts list in accordance with the access rights settings. The authentication_code, login and access_level parameters are available only to agents with the right to view contact’s access details. The last_seen parameter is available only for agents with the Administrator role.
Please note ¶
-
When transferring the search_string parameter, the other parameters are not considered
-
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace
-
The last_seen parameter has a 5-minute accuracy.
-
The contact search by phone or mobile phone number is carried out by matching last N digits ignoring separator characters (parentheses, hyphens, and others, that is, only numbers are taken into account). If more than 10 digits are sent, the last 10 will be used for search.
URI example
GET https://<account>.okdesk.com/api/v1/contacts/?api_token=3e9a214215f493c4&id=1024&email=employee@okdesk.com&phone=83214567788&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(optional) Example: 1024Internal contact ID
string(optional) Example: employee@okdesk.comContact e-mail or additional email address
- phone
string(optional) Example: 83214567788Contact phone or mobile phone
- search_string
string(optional) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 3020,
"name": "Housecoat Sally",
"last_name": "Housecoat",
"first_name": "Sally",
"patronymic": null,
"position": "Manager",
"email": "employee@okdesk.com",
"phone": "+79459999999",
"mobile_phone": "+79999999999",
"comment": "Senior Manager is responsible for Strategic Planning",
"cc_email": "employee@okdesk.com",
"telegram_username": "egorov",
"active": true,
"login": "egorov3020",
"crm_1c_id": "67067c3349a8",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"company_id": 1,
"company_name": "Company name",
"additional_emails": "contact@okdesk.com, contact2@okdesk.com",
"access_level": [
"company_issues"
],
"maintenance_entity_ids": [
12
],
"authentication_code": "6920-6310-7466-4123",
"observers": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"default_assignee": {
"id": 1,
"name": "John Smith"
},
"parameters": [
{
"code": "attr1",
"name": "Contact number",
"field_type": "ftstring",
"value": "2368590"
}
],
"observable_companies": [
{
"id": 1040,
"name": "Okdesk"
},
{
"id": 1041,
"name": "Acme Ltd."
}
],
"last_seen": "2019-09-30T15:12:09.095+03:00"
}Creating a contact
POST/api/v1/contacts/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| first_name | string | required | Name |
| last_name | string | required | Last name |
| patronymic | string | optional | Middle name |
| telegram_username | string | optional | Contact’s Telegram account |
| position | string | optional | Title |
| login | string | optional | Contact login |
| password | string | optional | Contact password |
| string | optional | Contact e-mail address | |
| additional_emails | string | optional | Additional emails |
| phone | string | optional | Phone number |
| mobile_phone | string | optional | Mobile phone number |
| comment | string | optional | Additional information on the contact |
| company_id | string | optional | ID of the company to which the contact is referenced (contact without reference to any company is allowed) |
| observer_ids | array of string | optional | Array of ID of users who are contact’s viewers |
| default_assignee_id | string | optional | The ID of agent assigned responsible for this contact by default |
| access_level | array of string | optional | The level of access to the contact’s profile. May include the following values: company_issues (view company’s tickets), maintenance_entities_issues (show tickets referenced to service aims), observable_companies_issues (show monitored company’s tickets), access_to_reports_for_company (access to your company’s reports), access_to_reports_for_external_companies (access to reports on monitored companies), allow_close_company_issues (allow closing all company tickets), allow_close_observable_companies_issues (allow closing monitored companies tickets), allow_close_maintenance_entity_issues (allow closing tickets related to assigned service aims), allow_viewing_issue_services (allow viewing ticket quantities), allow_editing_issue_services (allow editing ticket quantities), allow_viewing_issue_sidebar_time_entries (allow viewing the breakdown of the time spent on the ticket), allow_issue_confirmation (allow ticket approval) |
| cc_email | string | optional | Email for CC |
| maintenance_entity_ids | array of integer | optional | Array of service aim IDs |
| observable_company_ids | array of integer | optional | Array of viewed company IDs |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Contact extended attributes |
Please note ¶
-
Contact will not be created, if the service aim IDs (maintenance_entity_ids) do not correspond to the company’s ID (company_id).
-
The last_seen parameter has a 5-minute accuracy.
Restriction of access rights ¶
Creation of a contact person is available for agents in accordance with the settings of access rights. You can specify a login, password, as well as the level of access to your personal account only if the key-linked agent has the rights to edit the contact’s access details. It is only possible to specify a link with a company and companies being monitored when creating a contact if the key-linked agent has the right to add contact persons to the company in accordance with the access rights settings. Specifying a link to service aims when creating a contact will be possible only if the key-linked agent has the right to add contact persons to the service aim in accordance with the settings of access rights. Only contacts with the reference to the corresponding company can be created for the keys associated with contacts. Transferred values of “Responsible manager” and “Viewers by default” parameters will be ignored for the keys associated with contacts. The authentication_code, login and access_level parameters are available only to agents with the right to view contact’s access details. The last_seen parameter is available only for agents with the Administrator role.
URI example
POST https://<account>.okdesk.com/api/v1/contacts/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"contact": {
"first_name": "Joe",
"last_name": "Meatball",
"patronymic": "Smith",
"telegram_username": "joe",
"position": "Manager",
"login": "employee@okdesk.com",
"password": "strong_password",
"email": "employee@okdesk.com",
"additional_emails": "contact@okdesk.com, contact2@okdesk.com",
"phone": "+79459999999",
"mobile_phone": "+79999999999",
"comment": "Senior Manager is responsible for Strategic Planning",
"company_id": "1",
"observer_ids": [
"1",
"2"
],
"default_assignee_id": "1",
"cc_email": "egorov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"access_level": [
"access_to_reports_for_company"
],
"maintenance_entity_ids": [
15
],
"observable_company_ids": [
1040,
1041
],
"custom_parameters": {
"code2": "2019-02-15"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 3020,
"name": "Joe Meatball Smith",
"last_name": "Joe",
"first_name": "Meatball",
"patronymic": "Smith",
"telegram_username": "joe",
"position": "Manager",
"email": "employee@okdesk.com",
"phone": "+79459999999",
"mobile_phone": "+79999999999",
"comment": "Senior Manager is responsible for Strategic Planning",
"company_id": 1,
"company_name": "Company name",
"additional_emails": "contact@okdesk.com, contact2@okdesk.com",
"cc_email": "egorov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"updated_at": "2019-09-30T17:30:08.288+03:00",
"active": true,
"observers": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"access_level": [
"access_to_reports_for_company"
],
"maintenance_entity_ids": [
15
],
"default_assignee": {
"id": 1,
"name": "John Smith"
},
"authentication_code": "6920-6310-7466-4123",
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2019-02-15"
}
],
"observable_companies": [
{
"id": 1040,
"name": "Okdesk"
},
{
"id": 1041,
"name": "Acme Ltd."
}
],
"last_seen": "2019-09-30T15:12:09.095+03:00"
}Editing a contact
PATCH/api/v1/contacts/{contact_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| first_name | string | optional | Name |
| last_name | string | optional | Last name |
| patronymic | string | optional | Middle name |
| telegram_username | string | optional | Contact’s Telegram account |
| position | string | optional | Title |
| string | optional | Contact e-mail address | |
| additional_emails | string | optional | Additional emails |
| login | string | optional | Contact login |
| password | string | optional | Contact password |
| phone | string | optional | Phone number |
| mobile_phone | string | optional | Mobile phone number |
| company_id | string | optional | ID of the company to which the contact is referenced (contact without reference to any company is allowed) |
| access_level | array of string | optional | The level of access to the contact’s profile. May include the following values: company_issues (view company’s tickets), maintenance_entities_issues (show tickets referenced to service aims), observable_companies_issues (show monitored company’s tickets), access_to_reports_for_company (access to your company’s reports), access_to_reports_for_external_companies (access to reports on monitored companies), allow_close_company_issues (allow closing all company tickets), allow_close_observable_companies_issues (allow closing monitored companies tickets), allow_close_maintenance_entity_issues (allow closing tickets related to assigned service aims), allow_viewing_issue_services (allow viewing ticket quantities), allow_editing_issue_services (allow editing ticket quantities), allow_viewing_issue_sidebar_time_entries (allow viewing the breakdown of the time spent on the ticket), allow_issue_confirmation (allow ticket approval) |
| cc_email | string | optional | Email for CC |
| maintenance_entity_ids | array of integer | optional | Array of service aim IDs |
| observable_company_ids | array of integer | optional | Array of viewed company IDs |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| custom_parameters | associative array | optional | Contact extended attributes |
Please note ¶
-
The contact will not be modified, if the service aim IDs (maintenance_entity_ids) do not correspond to the transferred company ID (company_id).
-
If the company’s ID (company_id) has not been transferred in the course of contact editing, then the service aim’s correspondence will be checked for the contact’s current company.
-
The last_seen parameter has a 5-minute accuracy.
Restriction of access rights ¶
Editing of the contact will be completed only if the key-linked agent has the rights to view the contact’s card and edit the contact’s attributes in accordance with the access rights settings. The authentication_code, login and access_level parameters are available only to agents with the right to view contact’s access details. The last_seen parameter is available only for agents with the Administrator role. It is only possible to specify a link with a company and companies being monitored if the key-linked agent has the right to add contact persons to the company in accordance with the access rights settings. Specifying a link to service aims will be possible only if the key-linked agent has the right for adding contact persons to the service aim in accordance with the settings of access rights.
URI example
PATCH https://<account>.okdesk.com/api/v1/contacts/10?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- contact_id
integer(required) Example: 10Contact ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"contact": {
"first_name": "John",
"last_name": "Doe",
"patronymic": "Smith",
"telegram_username": "john",
"position": "Manager",
"login": "ivanov",
"password": "strong_password",
"email": "ivanov@okdesk.com",
"additional_emails": "contact@okdesk.com, contact2@okdesk.com",
"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
200HideShow
Headers
Content-Type: application/jsonBody
{
"sequential_id": 10,
"name": "Doe John Smith",
"first_name": "John",
"last_name": "Doe",
"patronymic": "Smith",
"telegram_username": "john",
"position": "Manager",
"email": "ivanov@okdesk.com",
"login": "ivanov",
"phone": "+79452222222",
"mobile_phone": "+73333333333",
"company_id": 33,
"company_name": "Company name",
"additional_emails": "contact@okdesk.com, contact2@okdesk.com",
"cc_email": "ivanov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"active": true,
"updated_at": "2019-09-30T15:12:09.095+03:00",
"access_level": [
"company_issues"
],
"authentication_code": "6920-6310-7466-4123",
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2019-02-15"
}
],
"observable_companies": [
{
"id": 1040,
"name": "Okdesk"
},
{
"id": 1041,
"name": "Acme Ltd."
}
],
"last_seen": "2019-09-30T15:12:09.095+03:00"
}Archiving contacts
PATCH/api/v1/contacts/{id}/activations{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| active | boolean | required | Contact activation status |
Restriction of access rights ¶
Contact archiving is available to agents in accordance with the settings of access rights.
URI example
PATCH https://<account>.okdesk.com/api/v1/contacts/1/activations?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 1contact ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"active": true
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"sequential_id": 10,
"name": "Doe John Smith",
"first_name": "John",
"last_name": "Doe",
"patronymic": "Smith",
"position": "Manager",
"email": "ivanov@okdesk.com",
"login": "ivanov",
"phone": "+79452222222",
"mobile_phone": "+73333333333",
"company_id": 33,
"company_name": "Company name",
"additional_emails": "contact@okdesk.com, contact2@okdesk.com",
"cc_email": "ivanov@okdesk.com",
"crm_1c_id": "67067c3a29a8",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"active": true,
"access_level": [
"company_issues"
],
"authentication_code": "6920-6310-7466-4123",
"parameters": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2019-02-15"
}
],
"observable_companies": [
{
"id": 1040,
"name": "Okdesk"
},
{
"id": 1041,
"name": "Acme Ltd."
}
],
"last_seen": "2019-09-30T15:12:09.095+03:00"
}Obtaining list by parameters
GET/api/v1/contacts/list{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| company_ids | array of integer | optional | Array of company IDs (set the value “0” to the parameter to show contacts without a company). Example: company_ids[]=1 |
| default_assignee_ids | array of integer | optional | Array of IDs of agents who are responsible for the contacts (set the value “0” to the parameter to show contacts without a responsible agent). Example: default_assignee_ids[]=1 |
| default_assignee_group_ids | array of integer | optional | Array of contact responsible group IDs (set the value “0” to the parameter to show contacts without a responsible group). Example: default_assignee_group_ids[]=1 |
| observer_ids | array of integer | optional | Array of IDs of agents who are viewers for the contacts (set the value “0” to the parameter to show contacts without a viewer). Example: observer_ids[]=1 |
| observer_group_ids | array of integer | optional | Array of contact viewer group IDs (set the value “0” to the parameter to show contacts without viewer groups). Example: observer_group_ids[]=1 |
| active | string | optional | Activity status. Takes true or false value |
| created_since | string | optional | The date the contact was created in the account’s time zone (From) Example: created_since=2019-05-25 |
| created_until | string | optional | The date the contact was created in the account’s time zone (Until) Example: created_until=2019-05-25 |
| updated_since | string | optional | The date the contact was modified in the account’s time zone (From) Example: updated_since=2019-05-25 |
| updated_until | string | optional | The date the contact was modified in the account’s time zone (Until) Example: updated_until=2019-05-25 |
| custom_parameters | associative array | optional | Associative array of Extended attribute code pairs: Value or set of values |
| page | associative array | optional | Associative array of parameters for a per-page display of the contact list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the contact starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the contact id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the contact’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the contact’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
Retrieving of the contacts list will be completed only if the key-linked agent has access to the contacts list in accordance with the access rights settings. The last_seen parameter is available only for agents with the Administrator role.
Please note ¶
-
This method returns no more than 100 entries.
-
If the parameters of per-page display are not transferred, the list of the last 100 contacts created will be returned.
-
The last_seen parameter has a 5-minute accuracy.
Valid values of extended attributes: ¶
| Parameter type | Type | Description |
|---|---|---|
| Date | string | There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[date_code_since]=2018-01-01 custom_parameters[date_code_until]=2018-12-12 |
| Date/time | string | There are two value types available: The code of extended attribute_since sets the left boundary (From); and the code of extended attribute_until sets the right boundary of the range (Until). You can transfer one of these parameters or both of them. Example: custom_parameters[datetime_code_since]=2018-01-01 01:01 custom_parameters[datetime_code_until]=2018-12-12 12:12 |
| Checkbox | string | Two values – true and false – are available. Example: custom_parameters[checkbox_code]=true |
| List item | array of string | An array of list values. Example: custom_parameters[list_code][]=list_value |
| List item set | array of string | An array of list values. Example: custom_parameters[list_code][]=list_value |
An example of a query with the contact list per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/contacts/list?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/contacts/list?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 9,
"name": "Doe John Smith",
"first_name": "John",
"last_name": "Doe",
"patronymic": "Smith",
"position": "Manager",
"active": true,
"email": "mail@johndoe.com",
"phone": "+79876543210",
"mobile_phone": "+71234567890",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"company_id": 2,
"company_name": "Company name",
"additional_emails": "contact@okdesk.com, contact2@okdesk.com",
"last_seen": "2019-09-30T15:12:09.095+03:00",
"parameters": [
{
"code": "attr1",
"name": "Contact number",
"field_type": "ftstring",
"value": "2368590"
}
]
},
{
"id": 8,
"name": "Castle Frank Rook",
"first_name": "Frank",
"last_name": "Castle",
"patronymic": "Rook",
"position": "Expert",
"active": true,
"email": "mail@frankcastle.com",
"phone": "+79876543211",
"mobile_phone": "+71234567899",
"updated_at": "2019-09-30T15:12:09.095+03:00",
"company_id": 2,
"company_name": "Company name",
"additional_emails": "contact@okdesk.com, contact2@okdesk.com",
"last_seen": "2019-09-30T15:12:09.095+03:00",
"parameters": [
{
"code": "attr1",
"name": "Contact number",
"field_type": "ftstring",
"value": "2368591"
}
]
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- search_string
string(required) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"title": "Service contract No.2016-03/1",
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"crm_1c_id": "desktop_1",
"active": false,
"company_ids": [
1
],
"default_assignee": {
"employee": {
"id": 1,
"name": "John Smith"
},
"group": {
"id": 1,
"name": "Targeting"
}
},
"observers": {
"employees": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"groups": [
{
"id": 5,
"name": "Quality control"
}
]
},
"service_periods": [
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
}
]
}
]Contract info
GET/api/v1/agreements/{id}{?api_token}
Restriction of access rights ¶
Contract info will be provided only if the key-linked agent has the right to view the сontract in accordance with the settings of access rights.
URI example
GET https://<account>.okdesk.com/api/v1/agreements/1?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 1Contract ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"title": "Service contract No.2016-03/1",
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"crm_1c_id": "67067c3a29a8",
"active": true,
"company_ids": [
1
],
"default_assignee": {
"employee": {
"id": 1,
"name": "John Smith"
},
"group": {
"id": 1,
"name": "Targeting"
}
},
"observers": {
"employees": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"groups": [
{
"id": 5,
"name": "Quality control"
}
]
},
"billing_status": "active_now",
"service_periods": [
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
}
]
}Editing the contract
PATCH/api/v1/agreements/{id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| title | string | optional | Contract name |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| active | boolean | optional | Contract activation status |
| default_assignee_id | integer | optional | ID of responsible agent by default |
| default_assignee_group_id | integer | optional | ID of responsible group by default |
| observer_ids | array of int | optional | Array of IDs of users viewing the contract |
| observer_group_ids | array of int | optional | Array of IDs of agent groups viewing the contract |
| company_ids | array | optional | Array of company IDs. To remove companies from the contract, you need to transfer the value [] |
| custom_parameters | associative array | optional | Contract extended attributes |
Restriction of access rights ¶
Editing of the contract will be completed only if the key-linked agent has the rights to view the contract, close the contract, editing the contract binding to the company and edit the contract attributes in accordance with the access rights settings. This method is not available for contact-associated keys.
URI example
PATCH https://<account>.okdesk.com/api/v1/agreements/1?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 1Contract ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"agreement": {
"title": "Service contract No.2016-03/1",
"crm_1c_id": "67067c3a29a8",
"active": false,
"company_ids": [
1,
2
],
"observer_ids": [
1,
2
],
"custom_parameters": {
"code2": "2019-02-15"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"title": "Service contract No.2016-03/1",
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"crm_1c_id": "67067c3a29a8",
"active": false,
"company_ids": [
1,
2
],
"default_assignee": {
"employee": {
"id": 1,
"name": "John Smith"
},
"group": {
"id": 1,
"name": "Targeting"
}
},
"observers": {
"employees": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"groups": [
{
"id": 5,
"name": "Quality control"
}
]
},
"service_periods": [
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}
],
"parameters": [
{
"code": "code2",
"name": "Contract date",
"field_type": "ftdate",
"value": "2019-02-15"
}
]
}Creating a contract
POST/api/v1/companies/{company_id}/agreements{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| title | string | required | Contract name |
| crm_1c_id | string | optional | Object ID in 1C, required to integrate with 1C; is not displayed in the web interface |
| default_assignee_id | integer | optional | ID of responsible agent by default |
| default_assignee_group_id | integer | optional | ID of responsible group by default |
| observer_ids | array of int | optional | Array of IDs of users viewing the contract |
| observer_group_ids | array of int | optional | Array of IDs of agent groups viewing the contract |
| custom_parameters | associative array | optional | Contract extended attributes |
Restriction of access rights ¶
Creating a contract is possible only if the agent associated with the key has the right to create an contract and to add an contract to the company. This method is not available for contact-associated keys.
URI example
POST https://<account>.okdesk.com/api/v1/companies/1/agreements?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- company_id
integer(required) Example: 1Company ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"agreement": {
"title": "Service contract No.2016-03/1",
"crm_1c_id": "67067c3a29a8",
"custom_parameters": {
"code2": "2019-02-12"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"title": "Service contract No.2016-03/1",
"start_date": null,
"end_date": null,
"cost": 0,
"crm_1c_id": "67067c3a29a8",
"active": true,
"company_ids": [
1
],
"default_assignee": {
"employee": {
"id": 1,
"name": "John Smith"
},
"group": {
"id": 1,
"name": "Targeting"
}
},
"observers": {
"employees": [
{
"id": 2,
"name": "Fred Bloggs"
},
{
"id": 1,
"name": "John Smith"
}
],
"groups": [
{
"id": 5,
"name": "Quality control"
}
]
},
"service_periods": [],
"parameters": [
{
"code": "code2",
"name": "Contract date",
"field_type": "ftdate",
"value": "2019-02-12"
}
]
}Obtaining a list of company contracts
GET/api/v1/companies/{company_id}/agreements{?api_token}
Please note ¶
This method returns list of contracts IDs associated with the assigned company.
Restriction of access rights ¶
The method is only available for keys associated with the user roles “Administrator” or “Leading Expert”.
URI example
GET https://<account>.okdesk.com/api/v1/companies/1/agreements?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- company_id
integer(required) Example: 1Company ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
1,
4,
5,
7
]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: 3e9a214215f493c4Authorization key.
- agreement_id
integer(required) Example: 1Contract ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"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
200HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- agreement_id
integer(required) Example: 1Contract ID.
- id
integer(required) Example: 1Service term ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"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
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"agreement_id": 1,
"start_date": "23-04-2018",
"end_date": "24-04-2018",
"cost": 322,
"comment": "Comment",
"reminder_date": "24-04-2018",
"postpay": false,
"paid": true
}Removing the service term
DELETE/api/v1/agreements/{agreement_id}/service_periods/{id}{?api_token}
Restriction of access rights ¶
Removing the service term will be completed only if the key-linked agent has the rights to view the card of contract and removing the contract service periods in accordance with the access rights settings. This method is not available for contact-associated keys.
URI example
DELETE https://<account>.okdesk.com/api/v1/agreements/1/service_periods/1?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- agreement_id
integer(required) Example: 1Contract ID.
- id
integer(required) Example: 1Service term ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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”. |
| repeat_params | associative array | optional | Ticket repeat parameters |
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.
Ticket repeat parameters: ¶
| Field Name | Type | Mandatory | Description |
|---|---|---|---|
| repeat_at | string | required | Date/time of the next repeat (must be no earlier than the start of the next day) |
| repeat_period | integer | required | Repeat period (possible values: from 1 to 999) |
| repeat_period_type | integer | required | Repeat type (possible values: 0 => day, 1 => week, 2 => month) |
| copy_checklist_from_previous | boolean | optional | Copy checklist from the previous ticket (possible values: true or false) |
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: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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
],
"repeat_params": {
"repeat_at": "2018-05-09 09:15",
"repeat_period": 3,
"repeat_period_type": 0,
"copy_checklist_from_previous": true
}
}
}Request
with attached filesHideShow
Headers
Content-Type: multipart/form-dataBody
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
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 237
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"issue": {
"title": "Broken socket",
"company_id": "-5",
"type": "unknown",
"priority": 'high',
"custom_parameters": {
"total": "4"
},
"parent_id": "102",
"repeat_params": {
"repeat_at": "2018-05-09 09-15",
"repeat_period": -1,
"repeat_period_type": 3,
"copy_checklist_from_previous": ""
}
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"company_id": "Entry -5 does not exist",
"type": "Entry unknown does not exist",
"custom_parameters_total": "the extended parameter total does not exist",
"repeat_params": {
"repeat_at": [
"has invalid format"
],
"repeat_period": [
"must be greater than 0"
],
"repeat_period_type": [
"must be one of: 0, 1, 2"
],
"copy_checklist_from_previous": [
"must be a boolean"
]
}
}
}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 ¶
Changing the responsibility for a ticket will be performed only if the user associated with the key has the rights to view the ticket, change the responsible party, assign an employee as the responsible party or co-executor of the ticket in accordance with access rights settings. This method is not available for keys associated with contacts.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/assignees?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"assignee_id": "1",
"group_id": "4"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Adding a ticket co-executor
POST/api/v1/issues/{issue_id}/coexecutors{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| coexecutor_id | integer | required | Coexecutor ID |
| group_id | integer | optional | Coexecutor group ID |
Restriction of access rights ¶
Adding a co-executor to a ticket will be performed only if the user associated with the key has the rights to view the ticket, edit the co-executors of the ticket, assign an employee as the responsible party or co-executor of the ticket in accordance with access rights settings. This method is not available for keys associated with contacts.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
POST https://<account>.okdesk.com/api/v1/issues/763/coexecutors?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"coexecutor_id": 1,
"group_id": 4
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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": 1,
"name": "John Mactavish",
"group": {
"id": 4,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Removing a ticket co-executor
DELETE/api/v1/issues/{issue_id}/coexecutors{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| coexecutor_id | integer | required | Coexecutor ID |
Restriction of access rights ¶
Removing a ticket co-executor will be performed only if the user associated with the key has the right to view the ticket and to change the ticket coexecutors in accordance with the access rights settings. This method is not available for keys associated with contacts.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
DELETE https://<account>.okdesk.com/api/v1/issues/763/coexecutors?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"coexecutor_id": 1
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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": null,
"coexecutors": [],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Adding observer of the ticket
PATCH/api/v1/issues/{issue_id}/observers{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| observer_id | integer | required | observer ID |
| observer_type | string | required | observer type. Acceptable values: employee, contact, group. |
Restriction of access rights ¶
Adding an observer to a ticket will be performed only if the user associated with the key has the rights to view the ticket, edit the list of observers of the ticket, assign an employee as an observer of the ticket, or the right to add themselves to the observers of the ticket, in accordance with access rights settings. This method is not available for keys associated with contacts.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/observers?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"observer_id": 113,
"observer_type": "employee"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Removing a ticket observer
DELETE/api/v1/issues/{issue_id}/observers{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| observer_id | integer | required | observer ID |
| observer_type | string | required | observer type. Acceptable values: employee, contact, group. |
Restriction of access rights ¶
Removing observer for the ticket will be performed only if the user associated with the key has the right to view the ticket and editing the list of ticket observers or the right to adding yourself to the ticket observers list in accordance with the access rights settings. This method is not available for keys associated with contacts.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
DELETE https://<account>.okdesk.com/api/v1/issues/763/observers?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"observer_id": 113,
"observer_type": "employee"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 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.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/deadlines?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"deadline_at": "2019-09-24 14:35"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with incorrect dateHideShow
Headers
Content-Type: application/jsonBody
{
"deadline_at": "2019/09/24T14:35"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"deadline_at": [
"Invalid date"
]
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"deadline_at": [
"Date should be later than today"
]
}
}Change the “Delayed until” date of ticket
PATCH/api/v1/issues/{issue_id}/delays{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| delay_to | string | required | The time to which the application is postponed. |
Restriction of access rights ¶
The “Delayed until” date of ticket will be changed only if a key-related user has rights to view the ticket and change the “Delayed until” date, and if the ticket is in delayed status. This method is not available for keys associated with contacts.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the planned decision time has not been set manually. Counted in minutes.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/delays?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"delay_to": "2019-09-24 14:35"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": "2019-09-24T14:35:00.000+03:00",
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"remaining_time_according_to_standard": 2400,
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with incorrect dateHideShow
Headers
Content-Type: application/jsonBody
{
"delay_to": "2019/09/24T14:35"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"delay_to": [
"Invalid date"
]
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"delay_to": [
"cannot be earlier than the current time"
]
}
}Request
with non-delayed statusHideShow
Headers
Content-Type: application/jsonResponse
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": "The current ticket status is not delayed"
}Change type of ticket
PATCH/api/v1/issues/{issue_id}/types{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | ticket type code |
Restriction of access rights ¶
-
This method is only available for keys associated with agents who have access to actions “View the ticket”, “Ticket type change” (including the right to set the transferred type according to the setting “Except for setting of a ticket type”).
-
This method is not available for contact-associated keys.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/types?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"code": "service"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"code": 123
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"code": [
"must be a string"
]
}
}Change priority of ticket
PATCH/api/v1/issues/{issue_id}/priorities{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | ticket priority code |
Restriction of access rights ¶
- This method is available for keys associated with agents who have access to actions “View the ticket”, “Ticket priority change” (including the right to set the transferred priority according to the priority setting “Available to the agents with the following roles”), and for contacts according to the priority setting “Available for selection by client”.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/priorities?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"code": "service"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"code": 123
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"code": [
"must be a string"
]
}
}Change the link of the ticket to the client contract service aim or equipment
PATCH/api/v1/issues/{issue_id}/related_attributes{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| company_id | integer | optional | Company ID |
| contact_id | integer | optional | Contact ID |
| agreement_id | integer | optional | Contract ID |
| maintenance_entity_id | integer | optional | Service aim ID |
| equipment_ids | array of integer | optional | Array of equipment ID |
Restriction of access rights ¶
-
This method is only available for keys associated with agents who have access to actions “View the ticket”, “Change the link of the ticket to the client, contract, service aim, or equipment”.
-
This method is not available for contact-associated keys.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/related_attributes?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"company_id": 1,
"contact_id": 1,
"agreement_id": 1,
"maintenance_entity_id": 1,
"equipment_ids": [
1
]
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 1,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [
1
],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 1,
"name": "Sally Housecoat"
},
"agreement": {
"id": 1,
"title": "Service contract"
},
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"company_id": "Odin"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"company_id": [
"must be an integer"
]
}
}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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"custom_parameters": {
"address": "Moscow st 2",
"checked": true,
"datetime": "2018-05-09 09:15",
"multiselect": [
"five"
],
"select": "one",
"date": "2018-05-09"
}
}Response
200Request
with incorrect dateHideShow
Headers
Content-Type: application/jsonBody
{
"custom_parameters": {
"datetime": "Second Tuesday"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"base": [
[
{
"datetime": "The extended parameter has invalid date/time format Engineer's arrival date and time"
}
]
]
}
}Request
when attribute is requiredHideShow
Body
{
"custom_parameters": {
"total_sum": ""
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"base": [
"The extended parameter Total sum cannot be blank"
]
}
}Ticket address edit
PATCH/api/v1/issues/{issue_id}/addresses{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | string | required | String representation of the ticket address |
| coordinates | array of float | required | Ticket address coordinates |
Please note ¶
If a non-blank value of at least one parameter is transferred (value, coordinates), the second parameter is required and cannot be empty. If empty values are passed for both parameters, the address in the ticket shall be reset.
Restriction of access rights ¶
The change of the ticket address will be performed only if the user associated with the key has the right to view the ticket and to change the address in accordance with the access rights settings. This method is not available for keys associated with contacts.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/addresses?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"value": "22 Old Edinburgh Road, BEESTON CW6 9TU",
"coordinates": [
53.2184321,
44.9998082
]
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
when one of the parameters is emptyHideShow
Body
{
"value": null,
"coordinates": [
53.2184321,
44.9998082
]
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"address_with_coordinates": [
"The address and coordinates shall be both empty (to delete the ticket address) or both filled in (to edit the ticket address)"
]
}
}Ticket status change
POST/api/v1/issues/{issue_id}/statuses{?api_token}
Please note ¶
-
open, delayed, completed, and closed system statuses are defined for tickets by default.
-
You can expand the set of statuses and possible transitions between them in the Settings/Tickets/Ticket statuses section of your Okdesk account.
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | Status code |
| delay_to | string | optional | The time to which the application is postponed. The field is mandatory for delayed status only. For other statuses, this parameter will be ignored. |
| comment | string | optional | Comment to the status. For example, the reason for transition to a new status. You can set the bindingness of this parameter in the “Settings/Tickets/Ticket Status” section. |
| comment_public | boolean | optional | Comment availability flag. Takes true or false value |
| custom_parameters | associative array | optional | Ticket extended attributes that are available to the user to enter when switching to a new status or leaving the current status. |
| time_entry | array | optional | Array of time spents on the ticket that will be added upon changing the status. |
| assignee_id | string | optional | Responsible agent ID |
| group_id | string | optional | Agent’s responsible group ID |
| skip_options | array | optional | Array of flags allowing to skip sending notifications (skip_notifications), webhooks (skip_webhooks), automatic actions (skip_triggers) |
Please note ¶
-
The delay_to parameter is mandatory to switch to delayed status
-
The comment parameter is mandatory for delayed status by default
-
To change your ticket status in your account settings, the transition from the current status of the ticket to the status transferred in a query must be permitted
-
Parameter formatted_spent_time should be like 2 h 30 min or 2:30 or 2.5 hours, etc.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
with status completedHideShow
Headers
Content-Type: application/jsonBody
{
"code": "completed",
"comment": "Ticket-related works are fully complete",
"comment_public": true,
"assignee_id": "1",
"group_id": "3",
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
},
"time_entry": [
{
"formatted_spent_time": "12h45m",
"comment": "Adding time spent when the status is changed",
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
}
},
{
"formatted_spent_time": "1h45m",
"comment": "Adding time spent when the status is changed",
"custom_parameters": {
"code1": "123456789",
"code2": "2019-02-15",
"code3": true
}
}
],
"skip_options": [
"skip_triggers",
"skip_notifications",
"skip_webhooks"
]
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "Web form ticket",
"description": "",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with status delayedHideShow
Headers
Content-Type: application/jsonBody
{
"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
200HideShow
Headers
Content-Type: application/jsonBody
{
"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": [],
"remaining_time_according_to_standard": 2400,
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 254ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"content": "Very soon an engineer will come to you to solve the problem.",
"public": false,
"published_at": "2018-12-24T14:38:43.442+03:00",
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2018-12-24T09:28:50.499+03:00"
}
],
"author": {
"id": 15,
"name": "David Sarif",
"type": "employee"
}
},
{
"id": 2,
"content": "Thank you, look forward to it.",
"public": true,
"published_at": "2018-12-24T15:57:43.374+03:00",
"attachments": [],
"author": {
"id": 12,
"name": "James Jim Miller",
"type": "contact"
}
}
]Obtaining detailed list by parameters
GET/api/v1/issues/list{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| company_ids | array of integer | optional | Array of ticket-related company IDs (set the value “0” to the parameter to show tickets without a company). Example: company_ids[]=1&company_ids[]=2 |
| company_category_ids | array of integer | optional | Array of client category IDs (set the value “0” to the parameter to show tickets without a company and tickets with companies without categories) Example: company_category_ids[]=1 |
| 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 |
| 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 |
| coexecutor_ids | array of integer | optional | Array of ticket coexecutors IDs (set the value “0” to the parameter to show tickets without a coexecutor). Example: coexecutor_ids[]=1&coexecutor_ids[]=2 |
| observer_ids | array of integer | optional | Array of ticket observers IDs (set the value “0” to the parameter to show tickets without a observer). Example: observer_ids[]=1& observer_ids[]=2 |
| contact_observer_ids | array of integer | optional | Array of ticket contact observers ID (set the value “0” to the parameter to show tickets without a contact observer). Example: contact_observer_ids[]=1& contact_observer_ids[]=2 |
| observer_group_ids | array of integer | optional | Array of ticket group observers ID (set the value “0” to the parameter to show tickets without a observer group). Example: observer_group_ids[]=1& observer_group_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 |
| equipment_ids | array of integer | optional | Array of equipment IDs (set the value “0” to the parameter to show tickets without a equipments). Example: equipment_ids[]=1&equipment_ids[]=2 |
| status_codes | array of string | optional | Array of ticket status codes Example: status_codes[]=opened&status_codes[]=completed |
| status_codes_not | array of string | optional | Array of ticket status codes that are forbidden for the ticket Example: status_codes_not[]=opened& status_codes_not[]=completed |
| priority_codes | array of string | optional | Array of ticket priority codes Example: priority_codes[]=high&priority_codes[]=low |
| type_codes | array of string | optional | Array of ticket type codes Example: _type_codes[]=incident |
| created_since | string | optional | Date of ticket creation (From) Example: created_since=22-03-2022 15:30 |
| created_until | string | optional | Date of ticket creation (Until) Example: created_until=22-06-2022 18:00 |
| overdue | boolean | optional | Flag "Tickets with deadline expired". If the value in the field is true, then only tickets with the deadline expired will be selected Example: overdue=true |
| overdue_reaction | boolean | optional | Flag "Tickets with response time exceeded". If the value in the field is true, then only tickets with the response time exceeded will be selected Example: overdue_reaction=true |
| completed_since | string | optional | Date of ticket resolution (From) Example: completed_since=22-03-2022 15:30 |
| completed_until | string | optional | Date of ticket resolution (Until) Example: completed_until=22-06-2022 18:00 |
| updated_since | string | optional | Date of the last ticket update (From) Example: updated_since=03-12-2023 15:30 |
| updated_until | string | optional | Date of the last ticket update (Until) Example: updated_until=03-12-2023 18:00 |
| deadline_since | string | optional | Planned resolution date (From) Example: deadline_since=03-12-2023 15:30 |
| deadline_until | string | optional | Planned resolution date (Until) Example: deadline_until=06-12-2023 18:00 |
| without_answer | boolean | optional | Flag "Tickets without answer". If the field value is true, tickets not responded by agent are fetched, i.e. tickets that have no agent’s public comment after ticket registration or no agent’s public comment after the last client’s comment. If the field value is false, the tickets with the last agent’s public comment will be fetched. |
| author | associative array | optional | Associative array of Author type: Author ID (set the value “0” to the employee or contact parameter to show tickets without author). Valid types: employee, contact Example: author[employee][]=1&author[contact][]=1 |
| custom_parameters | associative array | optional | Associative array of Extended attribute code pairs: Value or set of values |
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.
Please note ¶
The last modification date updated_at for a contact person and an employee differ because some changes are not visible to contact persons, and therefore, for them, the last modification date does not change when such actions are taken. Events that change the date for an employee include: change of status, change of the person responsible, issue type, issue priority, company, contact, contract, values of additional attributes, planned resolution date, planned execution time (hours), parameter “Scheduled for”, time tracking entries, addition of comments or specifications. Events that change the date for a contact include: change of status, modification of additional attribute values, and addition of a public comment.
Please note ¶
Additional application attributes in the response can only be obtained by using the fields parameter. This method does not return additional attributes of the “Image” type.
Please note ¶
By default, the method returns a specific set of application fields. If necessary, a set of returned fields different from the default set can be specified. To do this, pass the parameter fields[issue] in the request with the names of the fields whose values need to be obtained. (Example: fields[issue]=id,title,parameters).
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]=21-01-2023& custom_parameters[date_code_until]=22-12-2023 |
| 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]=21-01-2023 01:01& custom_parameters[datetime_code_until]=22-12-2023 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 (pass #null to return tickets with empty attribute value). Example: custom_parameters[string_code]=string_value |
Allowed field values when passing a parameter fields[issue]: ¶
| Name | Description |
|---|---|
| id | Unique identifier of the ticket |
| title | Title of the ticket |
| created_at | Date of ticket creation |
| completed_at | Date of ticket resolution |
| deadline_at | Planned date of ticket resolution |
| delay_to | Values of the “Delayed until” field for the postponed status of the ticket |
| planned_reaction_at | Planned response time for the ticket |
| reacted_at | Time of response to the ticket |
| without_answer | Value of the “Without answer” flag |
| updated_at | Date of ticket modification |
| status | Status of the ticket |
| type | Type of the ticket |
| priority | Priority of the ticket |
| company | Company associated with the ticket |
| contact | Contact person for the ticket |
| service_object | Service object of the ticket |
| agreement | Contract of the ticket |
| equipments | Equipment related to the ticket |
| assignee | Responsible agent |
| coexecutors | Coexecutors |
| rate | Ticket rating |
| parameters | Additional attributes of the ticket |
URI example
GET https://<account>.okdesk.com/api/v1/issues/list?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"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",
"planned_reaction_at": "2022-05-24T16:42:59.000+03:00",
"reacted_at": "2022-05-25T16:42:59.000+03:00",
"delay_to": null,
"updated_at": "2024-06-26T17:18:47.812+03:00",
"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
422HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 254ticket ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"issue": {
"rate": "bad"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"rate": "Ticket No. {issue_id} has been rated as Bad"
}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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 153ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"name": "Delivery to the service center",
"quantity": 1,
"discount": 2,
"total": 600,
"comment": "",
"total_vat": 343.83,
"service": {
"nomenclature_item_id": 1,
"code": "timerateservice",
"unit": "field trip",
"item_type": "service"
},
"price_list": {
"id": 2,
"name": "Field services"
},
"performer": {
"id": 3,
"name": "Max Mustermann"
}
},
{
"id": 2,
"name": "Pay per time services",
"quantity": 3,
"discount": 2,
"total": 10290,
"comment": "Different billed pay per hour services",
"total_vat": 1569.66,
"service": {
"nomenclature_item_id": 2,
"code": "timerateservice",
"unit": "man-hour",
"item_type": "service"
},
"price_list": {
"id": 3,
"name": "Billed services"
},
"performer": {
"id": 1,
"name": "Jean Dupont"
}
}
]Adding quantities to a ticket
POST/api/v1/issues/{issue_id}/services{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| service_id | integer | required | ID of the quantities line from the price list |
| quantity | number | required | Quantity (non-negative number) |
| performer_id | integer | optional | Responsible agent ID |
| comment | string | optional | Comment |
| total | number | optional | Cost (non-negative number) |
| discount | integer | optional | Discount (integer from 0 to 100) |
Please note ¶
-
Transferred responsible agent (performer_id) must be an active employee.
-
If the total and discount parameters are transferred simultaneously, they must correspond to each other based on the cost in the corresponding price list line.
-
The transferred ID* of the quantities line (service_id) must correspond to the active line of the price list.
Restriction of access rights ¶
-
This method is not available for contact-associated keys.
-
This method is only available for keys associated with agents who have access to actions “View the ticket”, “View ticket quantities” and “Adding lines in the ticket quantities”.
-
If the user does not have the right to view the cost in the ticket quantities, the transferred values of the “total” and “discount” parameters will be ignored.
URI example
POST https://<account>.okdesk.com/api/v1/issues/153/services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 153ticket ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"issue_service": {
"service_id": 1,
"quantity": 1,
"performer_id": 3,
"comment": "Comment",
"discount": 2,
"total": 600
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"name": "Delivery to the service center",
"quantity": 1,
"discount": 2,
"total": 600,
"comment": "Comment",
"total_vat": 343.83,
"service": {
"nomenclature_item_id": 1,
"code": "timerateservice",
"unit": "field trip",
"item_type": "service"
},
"price_list": {
"id": 2,
"name": "Field services"
},
"performer": {
"id": 3,
"name": "Max Mustermann"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"issue_service": {
"service_id": "wrong_code",
"performer_id": 103,
"comment": "Comment",
"discount": 2.1,
"total": -600
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"service_id": [
"must be an integer"
],
"quantity": [
"is missing"
],
"performer_id": [
"The agent does not exist or is not activated"
],
"discount": [
"must be an integer"
],
"total": [
"must be greater than or equal to 0"
]
}
}Removing ticket quantity
DELETE/api/v1/issues/{issue_id}/services/{id}{?api_token}
Restriction of access rights ¶
-
This method is not available for contact-associated keys.
-
This method is only available for keys associated with agents who have access to actions “View the ticket”, “View ticket quantities” and “Editing lines in the ticket quantities”.
URI example
DELETE https://<account>.okdesk.com/api/v1/issues/254/services/8?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 254ticket ID.
- id
integer(required) Example: 8ticket quantity line ID.
Response
204Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"service_id": [
"This quantities item does not exist or have been deleted"
]
}
}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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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
200HideShow
Headers
Content-Type: application/jsonBody
{
"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 parametersHideShow
Headers
Content-Type: application/jsonBody
{
"time_entries": [
{
"formatted_spent_time": "60m",
"comment": "Packaging",
"custom_parameters": {
"address": "54 Churchill Street"
}
}
]
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"employee_id": [
"is missing"
],
"logged_at": [
"is missing"
]
}
}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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
- attachment_id
integer(required) Example: 22File ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1001,
"name": "Check equipment",
"required": false,
"visible_for_clients": true,
"checked_at": "2021-01-27T20:45:00.703+03:00",
"parameters": [
{
"param_type": "quantity",
"required": true,
"value": 5
},
{
"param_type": "text",
"required": true,
"value": "No leaks found"
},
{
"param_type": "string",
"required": true,
"value": "51BKB835225"
},
{
"param_type": "files",
"required": false,
"value": [
{
"id": 521,
"attachment_file_name": "check_photo.jpeg",
"attachment_file_size": 3243,
"created_at": "2021-04-23T17:20:27.937+03:00"
}
]
}
],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": 1,
"position": 1,
"checked_by_user_id": 2,
"checked": true
},
{
"id": 1002,
"name": "Sign a contract",
"required": true,
"required_for_transition_to_status_codes": ["completed", "closed"],
"required_for_transition_from_status_codes": [],
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": null,
"position": 2,
"checked_by_user_id": null,
"checked": false
},
]Ticket checklist creation
POST/api/v1/issues/{issue_id}/check_lists/items{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | required | Checklist item name. |
| item_type | string | required | Checklist item type. Can be point or header. |
| required_to_status_codes | array of string | optional | An array of status codes with the item execution required when switched thereto. Passed only for mandatory checklist items. |
| required_from_status_codes | array of string | optional | An array of status codes with the item execution required when switched therefrom. Passed only for mandatory checklist items. |
| visible_for_clients | boolean | optional | Visibility to client. |
| planned_execution_in_minutes | number | optional | Planned execution (in minutes) |
| parameters | associative array | optional | Checklist line parameters. May contain the keys files (“Photo” execution parameter), text (“Comment” execution parameter), string (“String” execution parameter) quantity (“Quantity” 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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"check_list": {
"items": [
{
"name": "Check tightness",
"item_type": "point",
"visible_for_clients": true,
"required_to_status_codes": [
"completed",
"closed"
],
"required_from_status_codes": [
"opened"
],
"planned_execution_in_minutes": 60,
"parameters": {
"text": "unrequired",
"files": "required",
"quantity": "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
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1584,
"name": "Check tightness",
"required": true,
"visible_for_clients": true,
"checked_at": null,
"parameters": [
{
"param_type": "quantity",
"required": true,
"value": null
},
{
"param_type": "files",
"required": true,
"value": []
},
{
"param_type": "text",
"required": false,
"value": null
}
],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": 1,
"position": 1,
"checked": false,
"checked_by_user_id": null
},
{
"id": 1585,
"name": "Documents",
"required": false,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"item_type": "header",
"parent_id": null,
"position": 2,
"checked": false,
"checked_by_user_id": null
},
{
"id": 1586,
"name": "Sign the inspection certificate",
"required": false,
"visible_for_clients": true,
"checked_at": null,
"parameters": [
{
"param_type": "text",
"required": true,
"value": null
},
{
"param_type": "string",
"required": true,
"value": null
}
],
"item_type": "point",
"parent_id": 1585,
"planned_execution_in_hours": null,
"position": 1,
"checked": false,
"checked_by_user_id": null
},
{
"id": 1587,
"name": "Check seal",
"required": false,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": 1,
"position": 3,
"checked": false,
"checked_by_user_id": null
}
]Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"items": [
{},
{
"children": [
{
"item_type": [
"must be one of: point, header"
]
}
]
}
]
}
}Ticket checklist creation from template
POST/api/v1/issues/{issue_id}/check_lists/templates/{template_id}/items{?api_token}
Restriction of access rights ¶
-
This method is only available for keys associated with agents who have access to actions “View the ticket”, “Create the checklist in the ticket”.
-
This method is not available for contact-associated keys.
Please note ¶
- Template ID is displayed in the list of templates when hovering over the name of the template.
URI example
POST https://<account>.okdesk.com/api/v1/issues/166/check_lists/templates/166/items?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
- template_id
integer(required) Example: 166template ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1584,
"name": "Check tightness",
"required": true,
"visible_for_clients": true,
"checked_at": null,
"parameters": [
{
"param_type": "files",
"required": true,
"value": []
},
{
"param_type": "text",
"required": false,
"value": null
}
],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": 1,
"position": 1,
"checked": false,
"checked_by_user_id": null
},
{
"id": 1585,
"name": "Documents",
"required": false,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"item_type": "header",
"parent_id": null,
"position": 2,
"checked": false,
"checked_by_user_id": null
},
{
"id": 1586,
"name": "Sign the inspection certificate",
"required": false,
"visible_for_clients": true,
"checked_at": null,
"parameters": [
{
"param_type": "text",
"required": true,
"value": null
},
{
"param_type": "string",
"required": true,
"value": null
}
],
"item_type": "point",
"parent_id": 1585,
"planned_execution_in_hours": null,
"position": 1,
"checked": false,
"checked_by_user_id": null
},
{
"id": 1587,
"name": "Check seal",
"required": false,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": 1,
"position": 3,
"checked": false,
"checked_by_user_id": null
}
]Response
404HideShow
Headers
Content-Type: application/jsonBody
{
"errors": "Record not found"
}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: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 166ticket ID.
- item_id
integer(required) Example: 1002checklist item ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"check_list_item": {
"checked": true,
"item_parameters": {
"text": "No leaks found",
"string": "51BKB835225",
"quantity": 5
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1001,
"name": "Check equipment",
"required": false,
"visible_for_clients": true,
"checked_at": "2021-01-27T20:45:00.703+03:00",
"parameters": [
{
"param_type": "quantity",
"required": true,
"value": 5
},
{
"param_type": "text",
"required": true,
"value": "No leaks found"
},
{
"param_type": "string",
"required": true,
"value": "51BKB835225"
}
],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": 1,
"position": 1,
"checked_by_user_id": 2,
"checked": true
},
{
"id": 1002,
"name": "Sign a contract",
"required": true,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": null,
"position": 2,
"checked_by_user_id": null,
"checked": false
},
]Request
with attached filesHideShow
Headers
Content-Type: multipart/form-dataBody
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.com/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
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1001,
"name": "Check equipment",
"required": false,
"visible_for_clients": true,
"checked_at": "2021-01-27T20:45:00.703+03:00",
"parameters": [
{
"param_type": "text",
"required": true,
"value": "No leaks found"
},
{
"param_type": "files",
"required": false,
"value": [
{
"id": 521,
"attachment_file_name": "check_photo.jpeg",
"attachment_file_size": 3243,
"created_at": "2021-04-23T17:20:27.937+03:00"
}
]
}
],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": 1,
"position": 1,
"checked_by_user_id": 2,
"checked": true
},
{
"id": 1002,
"name": "Sign a contract",
"required": true,
"visible_for_clients": false,
"checked_at": null,
"parameters": [],
"item_type": "point",
"parent_id": null,
"planned_execution_in_hours": null,
"position": 2,
"checked_by_user_id": null,
"checked": false
},
]Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"check_list_item": {
"checked": 1234
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"checked": [
"must be boolean"
]
}
}Changing the parent issue
PATCH/api/v1/issues/{issue_id}/parents{?api_token}
Valid request parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| parent_id | integer | optional | Parent ticket ID. |
Access Rights Restrictions ¶
-
The modification of the parent ticket will only be carried out if the employee associated with the key has the permissions to view the card of the attached and parent tickets when establishing the relation, has the rights to merge the ticket with another (as an attached ticket), or has the rights to view the list of attached tickets of the parent ticket according to the access rights settings.
-
When deleting the relation, the user must have access to the following: the rights to view the card of the attached ticket and the rights to view the list of attached tickets of the parent ticket according to the access rights settings.
-
This method is not available for keys associated with contacts.
Please note ¶
When passing a null value in the parent_id parameter in a mutable relationship, the parent, if any, is broken.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763/parents?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763ticket ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"parent_id": 15
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "New title",
"description": "New description",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": 15,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"parent_id": null
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "New title",
"description": "New description",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"parent_id": 123456789
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"parent_id": "The ticket No. 123456789 does not exist"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"parent_id": "14"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"parent_id": [
"must be an integer"
]
}
}Update Ticket
PATCH/api/v1/issues/{issue_id}{?api_token}
Valid request parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| title | string | optional | Ticket title |
| description | string | optional | Ticket description |
Access Rights Restrictions ¶
The ticket update will only be performed if the user associated with the key has the rights to view the ticket and edit the ticket attributes according to the access rights settings. This method is not available for keys associated with contacts.
Please note ¶
The title parameter cannot be passed with an empty value.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
PATCH https://<account>.okdesk.com/api/v1/issues/763?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763Ticket ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"issue": {
"title": "New title",
"description": "New description"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 763,
"title": "New title",
"description": "New description",
"created_at": "2016-03-15T18:05:17.568+03:00",
"completed_at": "2016-05-19T10:54:09.987+03:00",
"deadline_at": "2019-09-24T14:35:00.000+03:00",
"source": "from_employee",
"spent_time_total": 0,
"start_execution_until": "2016-03-16T09:05:17.568+03:00",
"planned_execution_in_hours": 12,
"planned_reaction_at": "2016-04-11T11:00:00.000+03:00",
"reacted_at": "2016-04-10T18:43:44.951+03:00",
"updated_at": "2016-08-23T09:39:35.428+03:00",
"delayed_to": null,
"company_id": 40,
"group_id": 3,
"coexecutors": [
{
"id": 3,
"name": "John Mactavish",
"group": {
"id": 1,
"name": "Targeting"
}
}
],
"service_object_id": null,
"equipment_ids": [],
"attachments": [
{
"id": 8,
"attachment_file_name": "photo.jpg",
"description": "Photo of malfunction",
"attachment_file_size": 4149,
"is_public": false,
"created_at": "2016-09-30T09:28:50.499+03:00"
}
],
"status_times": {
"opened": {
"total": "134 d, 15 h, 43 m",
"on_schedule_total": "36 d, 1 h, 25 m"
},
"completed": {
"total": "0 d, 0 h, 0 m",
"on_schedule_total": "0 d, 0 h, 0 m"
}
},
"parameters": [],
"comments": {
"count": 5,
"last_at": "2018-07-05T16:06:10.000+03:00"
},
"parent_id": null,
"child_ids": [],
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"title": ""
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"title": [
"cannot be blank"
]
}
}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 observers and agent observers (if the corresponding value of the attribute “Show ticket observers in the Client portal” is set in the settings of the Client portal);
-
Company;
-
Contact;
-
Service aim;
-
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;
-
Remaining time according to standard.
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.
Please note ¶
Remaining time according to standard (remaining_time_according_to_standard) is returned only if the application is in a pending status, and the planned decision time has not been set manually. Counted in minutes.
URI example
GET https://<account>.okdesk.com/api/v1/issues/153?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 153ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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": [],
"remaining_time_according_to_standard": 2400,
"type": {
"id": 2,
"code": "service",
"name": "Service",
"available_for_client": true
},
"priority": {
"code": "low",
"name": "Low"
},
"status": {
"code": "opened",
"name": "Opened"
},
"old_status": {
"code": "completed",
"name": "Completed"
},
"rate": {
"id": 3,
"value": "normal"
},
"address": {
"coordinates": [
53.2184321,
44.9998082
],
"value": "3709 Charter Street, Overland Park, KS 66210"
},
"observers": [
{
"id": 113,
"type": "employee",
"name": "Adam Jensen"
},
{
"id": 121,
"type": "employee",
"name": "Robert Bob Page"
}
],
"observer_groups": [
{
"id": 5,
"name": "Quality control"
}
],
"contact": {
"id": 3020,
"name": "Sally Housecoat"
},
"agreement": null,
"assignee": {
"id": 1,
"name": "John Smith"
},
"author": {
"id": 3020,
"name": "Sally Housecoat"
}
}Ticket deletion
DELETE/api/v1/issues/{issue_id}{?api_token}
Restriction of access rights ¶
Deletion of a ticket is available to agents in accordance with the settings of access rights. This method is not available for contact-associated keys.
URI example
DELETE https://<account>.okdesk.com/api/v1/issues/153?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 153ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- inventory_number
string(optional) Example: 1101040003532Equipment inventory number
- serial_number
string(optional) Example: 51BKB835225Equipment serial number
- search_string
string(optional) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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"
}
],
"warehouse": {
"id": 2,
"title": "Warehouse"
},
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
]
}Creation of equipment
POST/api/v1/equipments/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| equipment_type_code | string | required | Equipment type code |
| equipment_manufacturer_code | string | optional | Equipment manufacturer code |
| equipment_model_code | string | optional | Equipment model code |
| serial_number | string | optional | Serial number |
| inventory_number | string | optional | Inventory number |
| comment | string | optional | Comment |
| company_id | string | optional | The ID of the company linked to the equipment |
| maintenance_entity_id | string | optional | The ID of the service aim, to which the equipment is linked |
| parent_id | string | optional | Parent equipment ID |
| custom_parameters | associative array | optional | Equipment extended attributes |
| agreement_ids | associative array | optional | Set of equipment contract IDs |
Please note ¶
-
If the equipment_type_code or equipment_manufacturer_code does not correspond to the type and manufacturer codes of the equipment model (equipment_model_code), the equipment will not be created.
-
If the service aim ID (maintenance_entity_id) does not correspond to the company’s ID (company_id), the equipment will not be created.
-
If the contract ID from array (agreement_ids) does not correspond to the company’s ID (company_id), the equipment will not be created.
-
The equipment being created and parent equipment shall be associated with the same company and same service aim.
Restriction of access rights ¶
Creation of equipment is available to agents in accordance with the settings of access rights.
-
It is only possible to specify a link with a company if the key-linked agent has the right to add equipment to the company in accordance with the access rights settings.
-
Specifying a service aim will be possible only if the key-linked agent has the right to add equipment to the service aim in accordance with the settings of access rights.
-
Contracts can be specified only if the agent associated with the key has the right to edit the equipment binding to the contract in accordance with the access rights settings.
-
This method is not available for contact-associated keys.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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
200HideShow
Headers
Content-Type: application/jsonBody
{
"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"
}
],
"warehouse": null,
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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
422HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 13Equipment ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"equipment": {
"equipment_model_code": "x50sm",
"company_id": "4",
"maintenance_entity_id": "15",
"custom_parameters": {
"end_of_service_period": "16/03/2019"
}
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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"
}
],
"warehouse": {
"id": 2,
"title": "Warehouse"
},
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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
422HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 13Equipment ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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": ""
},
"warehouse": {
"id": 2,
"title": "Warehouse"
},
"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 |
| warehouse_ids | array of integer | optional | Array of warehouse IDs (set the value “0” to the parameter to show equipment without a warehouse). Example: warehouse_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: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"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,
"warehouse": {
"id": 2,
"title": "Warehouse"
},
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}
]Attaching files to a equipment
POST/api/v1/equipments/{id}/attachments/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| attachments | array | required | List of attached files |
Valid query attached files parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| attachment | string | required | Attachable file |
| description | string | optional | File description |
| is_public | boolean | optional | File availability |
Please note ¶
-
The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
-
If parameter is_public is not sent, availability flag for the attachable files will be equal to the value of settings parameter ‘Files by default’
Restriction of access rights ¶
Adding a file to a equipment is available to agents in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/3/attachments/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 3equipment ID.
Request
with attached filesHideShow
Headers
Content-Type: multipart/form-dataBody
curl -H "Content-Type: multipart/form-data"
-F "equipment[attachments][0][attachment]=@/home/user/file.jpg"
-F "equipment[attachments][0][is_public]=true"
-F "equipment[attachments][0][description]=Description"
https://<account>.okdesk.com/api/v1/equipments/{id}/attachments/{?api_token}
where @/home/user/file.jpg is a path to the local file
for windows path will be like @"C:/myfile.txt"Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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"
}
],
"warehouse": {
"id": 2,
"title": "Warehouse"
},
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
]
}Service aims ¶
Service aim search
GET/api/v1/maintenance_entities/{?api_token,name,comment,search_string}
The search is carried out by the exact match of the service aim name, comment or by substring
Please note ¶
If the names of multiple service aims match, all values fit the search criteria will be returned When transferring the search_string parameter, the other parameters are not considered
Restriction of access rights ¶
The service aim search will be performed only if the key-linked agent has access to a service aim list in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
GET https://<account>.okdesk.com/api/v1/maintenance_entities/?api_token=3e9a214215f493c4&name=Sales outlet No.13&comment=Comment&search_string=desk
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- name
string(optional) Example: Sales outlet No.13Name
- comment
string(optional) Example: CommentService aim additional info
- search_string
string(optional) Example: deskTarget substring
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"name": "Sales outlet No.13",
"address": null,
"comment": null,
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1040,
"active": true,
"timezone": {
"code": "Moscow",
"name": "Moscow",
"gmt": "+03:00"
},
"contacts_ids": [
23,
24,
63,
64,
65
],
"equipments_ids": [
8,
9
],
"coordinates": [
53.2184321,
44.9998082
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [
{
"id": 5,
"name": "Andrei Russo"
},
{
"id": 12,
"name": "Alix Mckay"
}
],
"observer_groups": [
{
"id": 23,
"name": "Mechanics"
},
{
"id": 3,
"name": "Drivers"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}
]Creating a service aim
POST/api/v1/maintenance_entities/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | required | Name |
| company_id | integer | required | Company ID |
| agreement_ids | array of int | optional | Contracts IDs |
| address | string | optional | Address. Warning! When transmitting the text part of the address, automatic substitution of the address coordinates (geocoding) is not provided. To have the address displayed on the map, you must further specify address coordinates in the coordinates parameter. You can convert the text part of the address into coordinates using geocoding services, for example, the Google Geocoding API, etc. |
| coordinates | array of float | optional | Service aim coordinates |
| timezone | string | optional | Service aim time zone |
| comment | string | optional | Service aim additional info |
| default_assignee_id | integer | optional | ID of responsible agent by default |
| default_assignee_group_id | integer | optional | ID of responsible group by default |
| schedule_id | integer | optional | Service aim schedule ID |
| observer_ids | array of int | optional | Array of IDs of users viewing the service aim |
| observer_group_ids | array of int | optional | Array of IDs of agent groups viewing the service aim |
| custom_parameters | associative array | optional | Extended attributes of service aim |
Please note ¶
The coordinates parameter is an array of two real numbers (-90 to 90 latitude and -180 to 180 longitude). The agreement_ids parameter must contain IDs of contracts of a company with company_id.
Restriction of access rights ¶
Creating a service aim is available to agents in accordance with the settings of access rights. It is only possible to specify a link with a company if the key-linked agent has the right to add a service aim to the company in accordance with the access rights settings. Specifying contracts is possible only if the agent associated with the key has the right to edit the link of the service aim to the contract in accordance with the access rights settings. This method is not available for keys linked to contact persons.
URI example
POST https://<account>.okdesk.com/api/v1/maintenance_entities/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"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
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 9,
"name": "Sales outlet No.13",
"address": "3709 Charter Street, Overland Park, KS 66210",
"comment": "Comment",
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1040,
"active": true,
"timezone": {
"code": "Moscow",
"name": "Moscow",
"gmt": "+03:00"
},
"coordinates": [
53.2184321,
44.9998082
],
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-15"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [
{
"id": 5,
"name": "Robyn Fuller"
},
{
"id": 12,
"name": "Alix Mckay"
}
],
"observer_groups": [],
"attachments": [],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"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
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"company": [
"Entry 9999999 does not exist"
]
}
}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: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 4Service aim ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"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
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 9,
"name": "Shop No. 15",
"address": "2537 Goldie Lane, Cincinnati, OH 45203",
"comment": "Comment",
"default_assignee_id": 14,
"default_assignee_group_id": 1,
"company_id": 1040,
"active": true,
"timezone": {
"code": "Samara",
"name": "Samara",
"gmt": "+04:00"
},
"coordinates": [
53.2184321,
44.9998082
],
"parameters": [
{
"code": "code1",
"name": "Document No.",
"field_type": "ftstring",
"value": "123456789"
},
{
"code": "code2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-15"
},
{
"code": "code3",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [],
"observer_groups": [
{
"id": 7,
"name": "Electricians"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 3,
"title": "Another Important Contract"
}
]
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"maintenance_entity": {
"name": ""
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"name": [
"cannot be blank"
]
}
}Service aim info
GET/api/v1/maintenance_entities/{id}{?api_token}
Restriction of access rights ¶
Service aim information will only be provided if the user associated with the key has the right to view the service aim. For keys associated with contact persons, only limited information will be returned, specifically:
-
The name of the service aim;
-
The address of the service aim;
-
The coordinates of the aim;
-
Additional attributes with display settings enabled in the client portal.
URI example
GET https://<account>.okdesk.com/api/v1/maintenance_entities/153?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 153Service aim ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"name": "Newco Service Center",
"address": "2365 Shobe Lane, Durango, CO 81301",
"comment": "",
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1,
"active": true,
"timezone": {
"code": "Kaliningrad",
"name": "Kaliningrad",
"gmt": "+02:00"
},
"contacts_ids": [
23,
24,
63,
64,
65
],
"equipments_ids": [
8,
9
],
"coordinates": [
53.2605796,
49.9179003
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [
{
"id": 5,
"name": "Jareth Charles"
}
],
"observer_groups": [
{
"id": 7,
"name": "Electricians"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}Obtaining list by parameters
GET/api/v1/maintenance_entities/list{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| company_ids | array of integer | optional | Array of company IDs. Example: company_ids[]=1 |
| agreement_ids | array of integer | optional | Array of contract IDs (set the value “0” to the parameter to show service aims without a contract). Example: agreement_ids[]=1 |
| default_assignee_ids | array of integer | optional | Array of responsible agent IDs (set the value “0” to the parameter to show service aims without a responsible agent). Example: default_assignee_ids[]=1 |
| default_assignee_group_ids | array of integer | optional | Array of responsible group IDs (set the value “0” to the parameter to show service aims without a responsible group). Example: default_assignee_group_ids[]=1 |
| created_since | string | optional | The date the service aim was created in the account’s time zone (From) Example: created_since=2019-05-25 |
| created_until | string | optional | The date the service aim was created in the account’s time zone (Until) Example: created_until=2019-05-25 |
| updated_since | string | optional | The date the service aim was modified in the account’s time zone (From) Example: updated_since=2019-05-25 |
| updated_until | string | optional | The date the service aim was modified in the account’s time zone (Until) Example: updated_until=2019-05-25 |
| name | string | optional | The name of maintenance entity. The filter is carried out by occurrence of a substring in the name. |
| 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]=forwardURI example
GET https://<account>.okdesk.com/api/v1/maintenance_entities/list?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 8,
"name": "Aim No.2",
"address": "Anytown",
"coordinates": [
55.755831,
37.617673
],
"company_id": 1,
"active": true,
"agreements": [
{
"id": 1,
"title": "Important Contract"
}
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
}
]
},
{
"id": 5,
"name": "Aim No.1",
"address": "Your Town",
"coordinates": [
59.869778,
30.278344
],
"company_id": 3,
"active": true,
"agreements": [],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "1168590"
}
]
}
]Attaching files to a service aim
POST/api/v1/maintenance_entities/{id}/attachments/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| attachments | array | required | List of attached files |
Valid query attached files parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| attachment | string | required | Attachable file |
| description | string | optional | File description |
| is_public | boolean | optional | File availability |
Please note ¶
-
The content of the query with attached files shall be multipart/form-data and contain the corresponding title.
-
If parameter is_public is not sent, availability flag for the attachable files will be equal to the value of settings parameter ‘Files by default’
Restriction of access rights ¶
Adding a file to a service aim is available to agents in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
POST https://<account>.okdesk.com/api/v1/maintenance_entities/153/attachments/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 153service aim ID.
Request
with attached filesHideShow
Headers
Content-Type: multipart/form-dataBody
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.com/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
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"name": "Newco Service Center"
"2365 Shobe Lane, Durango, CO 81301"
"comment": "",
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1,
"active": true,
"timezone": {
"code": "Moscow",
"name": "Moscow",
"gmt": "+03:00"
},
"contacts_ids": [
23,
24,
63,
64,
65
],
"equipments_ids": [
8,
9
],
"coordinates": [
53.2605796,
49.9179003
],
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [],
"observer_groups": [],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}Archiving service aim
PATCH/api/v1/maintenance_entities/{id}/activations{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| active | boolean | required | Service aim activation status |
Restriction of access rights ¶
Service aim archiving is available to agents in accordance with the settings of access rights.
URI example
PATCH https://<account>.okdesk.com/api/v1/maintenance_entities/1/activations?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 1service aim ID.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"active": true
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"name": "Sales outlet No.13",
"address": null,
"comment": null,
"default_assignee_id": 12,
"default_assignee_group_id": 1,
"company_id": 1040,
"active": true,
"timezone": {
"code": "Moscow",
"name": "Moscow",
"gmt": "+03:00"
},
"contacts_ids": [
23,
24,
63,
64,
65
],
"equipments_ids": [
8,
9
],
"coordinates": null,
"parameters": [
{
"code": "attr1",
"name": "Document No.",
"field_type": "ftstring",
"value": "2368590"
},
{
"code": "attr2",
"name": "Commencement date",
"field_type": "ftdate",
"value": "2019-02-06"
},
{
"code": "attr3",
"name": "Date of the next call",
"field_type": "ftdatetime",
"value": "2019-02-21T14:00:00.000+03:00"
},
{
"code": "attr4",
"name": "VIP Service",
"field_type": "ftcheckbox",
"value": true
},
{
"code": "attr5",
"name": "Type of activity",
"field_type": "ftselect",
"value": "Software"
},
{
"code": "attr6",
"name": "Types of premises",
"field_type": "ftmultiselect",
"value": [
"Head office",
"Recreation area"
]
}
],
"schedule": {
"id": 1,
"name": "On weekdays, 9 a.m. to 6 p.m."
},
"observers": [
{
"id": 5,
"name": "Andrei Russo"
},
{
"id": 12,
"name": "Alix Mckay"
}
],
"observer_groups": [
{
"id": 23,
"name": "Mechanics"
},
{
"id": 3,
"name": "Drivers"
}
],
"attachments": [
{
"attachment_file_name": "file.jpg",
"description": "Description",
"is_public": true,
"id": 575
}
],
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}Warehouses ¶
Obtaining a list of warehouses
GET/api/v1/warehouses{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| external_id | string | optional | External ID |
| page | associative array | optional | Associative array of parameters for a per-page display of the warehouse list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the warehouse starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the warehouse id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the warehouse’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the warehouse’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The list of warehouses will be provided only if the key-linked agent has access to a warehouse list in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 warehouses created will be returned.
An example of a query with the warehouse list per-page display parameters ¶
https://<account>.okdesk.com/api/v1/warehouses?
api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/warehouses?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 101,
"name": "Second warehouse",
"active": true,
"external_id": "112233",
"assignee_ids": [
1,
2
],
"observer_ids": []
},
{
"id": 100,
"name": "First warehouse",
"active": false,
"external_id": null,
"assignee_ids": [],
"observer_ids": [
1,
2
]
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Warehouse info
GET/api/v1/warehouses/{warehouse_id}{?api_token}
Restriction of access rights ¶
-
This method is not available for contact-associated keys.
-
This method is only available for keys associated with agents who have access to actions “Access to the Warehouses section”, “View warehouse in the list”
An example of a query: ¶
https://<account>.okdesk.com/api/v1/warehouses/100?api_token=3e9a214215f493c4
URI example
GET https://<account>.okdesk.com/api/v1/warehouses/100?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- warehouse_id
integer(required) Example: 100Warehouse ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 100,
"name": "First warehouse",
"active": false,
"external_id": null,
"assignee_ids": [],
"observer_ids": [
1,
2
]
}Obtaining a list of balances
GET/api/v1/material_assets/remainders{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| item_types | array of string | optional | Nomenclature type. Acceptable values: product, material. |
| page | associative array | optional | Associative array of parameters for a per-page display of the balance list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the nomenclature item starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the nomenclature item id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the nomenclature item’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the nomenclature item’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The list of balance will be provided only if the key-linked agent has access to a “Access to the Warehouses section” and “Viewing common balances” in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 balance created will be returned.
An example of a query with the balance list per-page display parameters ¶
https://<account>.okdesk.com/api/v1/material_assets/remainders?
api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/material_assets/remainders?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 101,
"code": "item_code2",
"name": "Nail",
"active": true,
"item_type": "product",
"unit": "kg.",
"vendor_code": "",
"quantity": 1.5
},
{
"id": 100,
"code": "item_code1",
"name": "Screw",
"active": true,
"item_type": "product",
"unit": "kg.",
"vendor_code": "",
"quantity": 2.5
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Obtaining a list of warehouse balances
GET/api/v1/warehouses/{warehouse_id}/remainders{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| page | associative array | optional | Associative array of parameters for a per-page display of the balance list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the nomenclature item starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the nomenclature item id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the nomenclature item’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the nomenclature item’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The list of warehouse balance will be provided only if the key-linked agent has access to a “Access to the Warehouses section” and “View warehouse card” in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 balance created will be returned.
An example of a query with the balance list per-page display parameters ¶
https://<account>.okdesk.com/api/v1/warehouses/100/remainders?
api_token=3e9a214215f493c4&page[size]=2&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/warehouses/100/remainders?api_token=3e9a214215f493c4
URI parameters
HideShow
- warehouse_id
integer(required) Example: 100Warehouse ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 101,
"code": "item_code2",
"name": "Nail",
"active": true,
"item_type": "product",
"unit": "kg.",
"vendor_code": "",
"quantity": 1.5
},
{
"id": 100,
"code": "item_code1",
"name": "Screw",
"active": true,
"item_type": "product",
"unit": "kg.",
"vendor_code": "",
"quantity": 2.5
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Creating an inventory record
POST/api/v1/material_assets/documents{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| doc_type | string | required | Document type. Valid values: posting, writing_off, moving |
| from_warehouse_id | integer | mandatory for documents with the write-off and transfer type | ID of the warehouse, from which the items will be written-off or transferred |
| to_warehouse_id | integer | mandatory for documents with the recognition and transfer type | ID of the warehouse, to which the items will be received or transferred |
| external_doc | string | optional | External document |
| accounted_at | string | optional | Document recording date |
Restriction of access rights ¶
An inventory record will be created only if a key-linked agent has access to the Warehouses section and rights to view the warehouse card, create and edit an inventory record in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
POST https://<account>.okdesk.com/api/v1/material_assets/documents?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"document": {
"doc_type": "writing_off",
"from_warehouse_id": 11,
"external_doc": "1475823",
"accounted_at": "12-01-2023"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 22,
"accounted_at": "2023-01-12",
"created_at": "2023-06-23T17:53:00.242+03:00",
"external_doc": "1475823",
"number": "000022",
"doc_type": {
"code": "writing_off",
"name": "Writing-off"
},
"status": {
"code": "drafted",
"name": "Draft"
},
"author_id": 1,
"from_warehouse": {
"id": 11,
"name": "Warehouse №11"
},
"to_warehouse": null
}Retrieve the document list
GET/api/v1/material_assets/documents{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| doc_types | array of string | optional | Array of document types. Valid values: posting, writing_off, moving. Example: doc_types[]=posting&doc_types[]=moving |
| statuses | array of string | optional | Array of document statuses. Valid values: drafted, waiting_for_approve, waiting_for_receive, accounted. Example: statuses[]=drafted&statuses[]=accounted |
| from_warehouses | array of integer | optional | Array of ID of warehouses, from which the items were written-off or transferred (From stock). Example: from_warehouses[]=1&from_warehouses[]=2 |
| to_warehouses | array of integer | optional | Array of ID warehouses, to which the items were received or transferred (To stock). Example: to_warehouses[]=1&to_warehouses[]=2 |
| external_doc | string | optional | External document. Example: external_doc=External |
| page | associative array | optional | Associative array of parameters for a per-page display of the document list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the inventory record starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the inventory record id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the inventory record’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the inventory record’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The list of inventory records will be retrieved only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
An example of a query with the document list per-page display parameters:: ¶
https://<account>.okdesk.com/api/v1/material_assets/documents?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/material_assets/documents?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 22,
"accounted_at": "2023-01-12",
"created_at": "2023-06-23T17:53:00.242+03:00",
"external_doc": "1475823",
"number": "000022",
"doc_type": {
"code": "writing_off",
"name": "Writing-off"
},
"status": {
"code": "drafted",
"name": "Draft"
},
"author_id": 1,
"from_warehouse": {
"id": 11,
"name": "Warehouse №11"
},
"to_warehouse": null
}
]Change status of inventory record
PATCH/api/v1/material_assets/documents/{document_id}/statuses{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | Record status code. Valid values: drafted, waiting_for_approve, waiting_for_receive, accounted |
Restriction of access rights ¶
An inventory record status will be changed only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card. To change the “Draft” status to the “Approval” status, the right “Create, edit an inventory record” shall be checked. To change the “Approval” status to “Recorded”, “Pending acceptance” or “Draft”, the right “Change status of inventory record” shall be checked. To change the status “Recorded” to “Draft”, the right “Cancel recorded documents” shall be checked. This method is not available for keys linked to contact persons.
URI example
PATCH https://<account>.okdesk.com/api/v1/material_assets/documents/12/statuses?api_token=3e9a214215f493c4
URI parameters
HideShow
- document_id
integer(required) Example: 12Inventory record ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"code": "waiting_for_approve"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 22,
"accounted_at": "2023-01-12",
"created_at": "2023-06-23T17:53:00.242+03:00",
"external_doc": "1475823",
"number": "000022",
"doc_type": {
"code": "writing_off",
"name": "Writing-off"
},
"status": {
"code": "waiting_for_approve",
"name": "Approval"
},
"author_id": 1,
"from_warehouse": {
"id": 11,
"name": "Warehouse №11"
},
"to_warehouse": null
}Retrieve inventory items in the inventory record
GET/api/v1/material_assets/documents/{document_id}/items{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| page | associative array | optional | Associative array of parameters for a per-page display of the inventory items (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the inventory item starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the inventory item id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the inventory item’s largest id. forward returns item with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the inventory item’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The list of inventory items in the inventory record will be retrieved only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
An example of a query with the inventory item per-page display parameters ¶
https://<account>.okdesk.com/api/v1/material_assets/documents/5/items?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/material_assets/documents/12/items?api_token=3e9a214215f493c4
URI parameters
HideShow
- document_id
integer(required) Example: 12Inventory record ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 4,
"nomenclature_item_id": 5,
"quantity": "2.0",
"code": "item_code2",
"name": "Nail",
"vendor_code": "",
"item_type": "product",
"unit": "kg."
},
{
"id": 5,
"nomenclature_item_id": 6,
"quantity": "1.5",
"code": "item_code1",
"name": "Screw",
"vendor_code": "",
"item_type": "product",
"unit": "kg."
}
]Create inventory item in the inventory record
POST/api/v1/material_assets/documents/{document_id}/items{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| nomenclature_item_id | integer | required | Nomenclature ID |
| quantity | float | required | Quantity |
Restriction of access rights ¶
The inventory item will be created in the inventory record only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card, create and edit the inventory record in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
POST https://<account>.okdesk.com/api/v1/material_assets/documents/12/items?api_token=3e9a214215f493c4
URI parameters
HideShow
- document_id
integer(required) Example: 12Inventory record ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"item": {
"nomenclature_item_id": 6,
"quantity": 3.2
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 6,
"nomenclature_item_id": 6,
"quantity": "3.2",
"code": "item_code1",
"name": "Screw",
"vendor_code": "",
"item_type": "product",
"unit": "kg."
}Remove inventory item from the inventory record
DELETE/api/v1/material_assets/documents/{document_id}/items/{item_id}{?api_token}
Restriction of access rights ¶
The inventory item will be removed from the inventory record only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card, create and edit the inventory record in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
DELETE https://<account>.okdesk.com/api/v1/material_assets/documents/12/items/6?api_token=3e9a214215f493c4
URI parameters
HideShow
- document_id
integer(required) Example: 12Inventory record ID.
- item_id
integer(required) Example: 6Inventory item ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"result": "Removed successfully"
}Retrieve equipment items in the inventory record
GET/api/v1/material_assets/documents/{document_id}/equipment_items{?api_token}
Valid query parameters:: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| page | associative array | optional | Associative array of parameters for a per-page display of the equipment items (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the equipment item starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment item id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment item’s largest id. forward returns item with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment item’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
The list of inventory items in the inventory record will be retrieved only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card, Add to equipment list, View enlisted equipment in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
An example of a query with the inventory item per-page display parameters ¶
https://<account>.okdesk.com/api/v1/material_assets/documents/5/equipment_items?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/material_assets/documents/12/equipment_items?api_token=3e9a214215f493c4
URI parameters
HideShow
- document_id
integer(required) Example: 12Inventory record ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 6,
"equipment": {
"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,
"warehouse": {
"id": 2,
"title": "Warehouse"
},
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}
}
]Create equipment item in the inventory record
POST/api/v1/material_assets/documents/{document_id}/equipment_items{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| equipment_id | integer | required | equipment ID |
Restriction of access rights ¶
The inventory item will be created in the inventory record only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card, create and edit the inventory record in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
POST https://<account>.okdesk.com/api/v1/material_assets/documents/12/equipment_items?api_token=3e9a214215f493c4
URI parameters
HideShow
- document_id
integer(required) Example: 12Inventory record ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_item": {
"equipment_id": 6
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 6,
"equipment": {
"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,
"warehouse": {
"id": 2,
"title": "Warehouse"
},
"agreements": [
{
"id": 2,
"title": "Important Contract"
}
]
}
}Remove equipment from the inventory record
DELETE/api/v1/material_assets/documents/{document_id}/equipment_items/{item_id}{?api_token}
Restriction of access rights ¶
The inventory item will be removed from the inventory record only if a key-linked agent has access to the Warehouses section and rights to view the inventory record card, create and edit the inventory record in accordance with the settings of access rights. This method is not available for keys linked to contact persons.
URI example
DELETE https://<account>.okdesk.com/api/v1/material_assets/documents/12/equipment_items/6?api_token=3e9a214215f493c4
URI parameters
HideShow
- document_id
integer(required) Example: 12Inventory record ID.
- item_id
integer(required) Example: 6Inventory item ID.
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
204Integration 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: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"telephony_numbers": [
123,
456
],
"search_numbers_count": 7,
"phone": "1232123"
}Response
200HideShow
Body
{}Making an entry about the phone call
POST/api/v1/phone_calls{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| call_id | string | required | Call ID in the external system |
| started_at | string | required | Call start date/time |
| finished_at | string | required | Call termination date/time |
| duration | integer | required | Call duration (in seconds) |
| direction | integer | required | Call direction (1 for outgoing and 0 for incoming) |
| receiver_phone | string | required | Receiving number |
| source_phone | string | required | Caller’s number |
| search_numbers_count | integer | required | Number of the last digits of the outside party’s number to find a match in the client database |
| file_url | string | optional | Link to download a file with a recording of a phone call |
| issue_id | integer | optional | Call ticket id |
Restriction of access rights ¶
The method is only available for key associated with the user role “Administrator”.
URI example
POST https://<account>.okdesk.com/api/v1/phone_calls?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"phone_call": {
"call_id": "test-123",
"started_at": "2019-02-24 09:16",
"finished_at": "2019-02-24 09:17",
"duration": 60,
"direction": 1,
"source_phone": "811111111111",
"receiver_phone": "82222222222",
"search_numbers_count": 10,
"file_url": "https://test.com/file.mp3",
"issue_id": 1
}
}Response
201Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"phone_call": {
"started_at": "2019-02-24 09:17",
"finished_at": "2019-02-24 09:16",
"duration": 60,
"direction": 3,
"source_phone": "811111111111",
"receiver_phone": "82222222222",
"search_numbers_count": -1,
"file_url": "https://test.com/file.mp3",
"issue_id": 1
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"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]=reverseURI example
GET https://<account>.okdesk.com/api/v1/price_lists?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 101,
"name": "Price list of maintenance",
"allow_without_category": false,
"allow_without_company": false,
"inverted_companies": false,
"company_category_codes": [
"partner",
"client",
"vipclient"
],
"company_ids": [
441,
41
]
},
{
"id": 100,
"name": "General services, works and materials price list of the company",
"allow_without_category": false,
"allow_without_company": false,
"inverted_companies": false,
"company_category_codes": [],
"company_ids": []
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Obtaining list line by parameters
GET/api/v1/nomenclature/price_lists/{price_list_id}/services{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in nomenclature item code, name, description, item number. |
| item_types | array of string | optional | Nomenclature type. Acceptable values: service, product, material, work. |
| group_id | string | optional | Nomenclature item group ID (set the value “0” to the parameter to show nomenclature items without group). |
| page | associative array | optional | Associative array of parameters for a per-page display of the price list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
This method is only available for keys associated with agents who have access to action “Access to price-list management”.
Please note ¶
-
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.
-
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace
An example of a query with the price list lines per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/nomenclature/price_lists/153/services?
api_token=3e9a214215f493c4&item_types[]=service&item_types[]=work&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/nomenclature/price_lists/154/services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- price_list_id
integer(required) Example: 154Price list ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 1,
"nomenclature_item_id": 1,
"code": "timerateservice",
"name": "Pay per time services",
"type": "service",
"group": {
"id": 1,
"code": "group_code",
"name": "Services"
},
"unit": "man-hour",
"vendor_code": "",
"price": 1000,
"nds": 0,
"visible": true,
"description": "Different billed pay per hour services"
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"item_types": {
"0": [
"must be one of: service, product, material, work"
]
},
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Price list line adding method
POST/api/v1/nomenclature/price_lists/{price_list_id}/services{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| nomenclature_item_id | integer | required | Nomenclature item ID. |
| price | number | required | Price |
| nds | integer | required | VAT rate, % |
Restriction of access rights ¶
This method is only available for keys associated with agents who have access to action “Access to price-list management”.
URI example
POST https://<account>.okdesk.com/api/v1/nomenclature/price_lists/154/services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- price_list_id
integer(required) Example: 154Price list ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"service": {
"nomenclature_item_id": 2,
"price": 1000,
"nds": 0
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"nomenclature_item_id": 2,
"code": "timerateservice",
"name": "Pay per time services",
"type": "service",
"group": {
"id": 1,
"code": "group_code",
"name": "Services"
},
"unit": "man-hour",
"vendor_code": "",
"price": 1000,
"nds": 0,
"visible": true,
"description": "Different billed pay per hour services"
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"service": {
"price": "wrong"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"nomenclature_item_id": [
"is missing"
],
"price": [
"must be a float or must be an integer"
]
}
}Price list line editing method
PATCH/api/v1/nomenclature/price_lists/{price_list_id}/services/{id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| price | number | optional | Price |
| nds | integer | optional | VAT rate, % |
| visible | boolean | optional | Activity status. Takes true or false value |
Restriction of access rights ¶
This method is only available for keys associated with agents who have access to action “Access to price-list management”.
URI example
PATCH https://<account>.okdesk.com/api/v1/nomenclature/price_lists/154/services/12?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- price_list_id
integer(required) Example: 154Price list ID.
- id
integer(required) Example: 12Price list line ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"service": {
"price": 2000,
"nds": 5,
"visible": false
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 1,
"nomenclature_item_id": 2,
"code": "timerateservice",
"name": "Pay per time services",
"type": "work",
"group": {
"id": 1,
"code": "group_code",
"name": "Services"
},
"unit": "man-hour",
"vendor_code": "",
"price": 2000,
"nds": 5,
"visible": true,
"description": "Different billed pay per hour services"
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"service": {
"price": "100",
"nds": 200,
"visible": 1
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"price": [
"must be a float or must be an integer"
],
"nds": [
"must be less than or equal to 100"
],
"visible": [
"must be a boolean"
]
}
}Obtaining available price list lines by parameters for ticket and user
GET/api/v1/issues/{issue_id}/available_services{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in price list line name |
| item_types | array of string | optional | Nomenclature type. Acceptable values: service, product, material, work. |
| page | associative array | optional | Associative array of parameters for a per-page display of the price list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to actions “View the ticket”, “Adding lines in the ticket quantities”.
Please note ¶
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 equipment types created will be returned.
An example of a query with the price list lines per-page display parameters ¶
https://<account>.okdesk.com/api/v1/issues/1/available_services?
api_token=3e9a214215f493c4&item_types[]=service&page[size]=3&page[from_id]=10&page[direction]=reverse&search_string=firstURI example
GET https://<account>.okdesk.com/api/v1/issues/763/available_services?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- issue_id
integer(required) Example: 763Ticket ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"price_list_id": 3,
"price_list_name": "Price list of maintenance",
"id": 1,
"nomenclature_item_id": 1,
"code": "timerateservice",
"name": "Pay per time services",
"type": "work",
"unit": "man-hour",
"price": 2000,
"nds": 5,
"vendor_code": "",
"description": "Different billed pay per hour services",
"group": {
"id": 1,
"code": "group_code",
"name": "Services"
}
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Nomenclature ¶
Obtaining nomenclature groups
GET/api/v1/nomenclature/groups{?api_token,search_string,code}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in nomenclature group name |
| code | string | optional | Nomenclature group code |
| page | associative array | optional | Associative array of parameters for a per-page display of the price list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to action “Access to price-list management”.
Please note ¶
-
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.
-
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace
An example of a query with the nomenclature groups per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/nomenclature/groups?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/nomenclature/groups?api_token=3e9a214215f493c4&search_string=Nested&code=group1
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- search_string
string(optional) Example: NestedTarget substring.
- code
string(optional) Example: group1Group code.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 101,
"code": "group1",
"name": "Nested group",
"active": true,
"group": {
"id": 100,
"code": "group2",
"name": "Parent group"
}
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Creation of nomenclature group
POST/api/v1/nomenclature/groups{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | Group code |
| name | string | required | Group name |
| parent_id | integer | optional | Parent group ID |
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to action “Access to price-list management”.
URI example
POST https://<account>.okdesk.com/api/v1/nomenclature/groups?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"nomenclature_group": {
"code": "group_code",
"name": "Pay per time services",
"parent_id": 99
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 100,
"code": "group_code",
"name": "Pay per time services",
"active": true,
"group": {
"id": 99,
"code": "parent_group_code",
"name": "Parent group"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"nomenclature_group": {
"code": true,
"parent_id": "incorrect_id"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"code": [
"must be a string"
],
"name": [
"is missing"
],
"parent_id": [
"must be an integer"
],
}
}Obtaining nomenclature group by id
GET/api/v1/nomenclature/groups/{id}{?api_token}
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to action “Access to price-list management”.
URI example
GET https://<account>.okdesk.com/api/v1/nomenclature/groups/100?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 100Group ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 100,
"code": "group_code",
"name": "Pay per time services",
"active": true,
"group": null
}Editing of nomenclature group
PATCH/api/v1/nomenclature/groups/{id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Group name |
| parent_id | integer | optional | Parent group ID |
| active | boolean | optional | Activity status. Takes true or false value |
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to action “Access to price-list management”.
URI example
PATCH https://<account>.okdesk.com/api/v1/nomenclature/groups/100?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 100Group ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"nomenclature_group": {
"name": "Pay per time services",
"parent_id": 99,
"active": false
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 100,
"code": "group_code",
"name": "Pay per time services",
"active": false,
"group": {
"id": 99,
"code": "parent_group_code",
"name": "Parent group"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"nomenclature_group": {
"active": "1"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"active": [
"must be a boolean"
]
}
}Obtaining nomenclature items list
GET/api/v1/nomenclature/items{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in nomenclature item name, code, item number |
| code | string | optional | Nomenclature item code |
| item_types | array of string | optional | Nomenclature type. Acceptable values: service, product, material, work. Example: item_types[]=work&item_types[]=service |
| group_id | integer | optional | Nomenclature item group ID (set the value “0” to the parameter to show nomenclature items without group) |
| page | associative array | optional | Associative array of parameters for a per-page display of the price list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the price list starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the price list id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the price list’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to action “Access to price-list management”.
Please note ¶
-
This method returns no more than 100 entries. If the parameters of per-page display are not transferred, the list of the last 100 price list lines created will be returned.
-
The + sign shall be used in the search box only in encrypted format as %2B. Otherwise, it will be interpreted as a whitespace
An example of a query with the nomenclature items per-page display parameters: ¶
https://<account>.okdesk.com/api/v1/nomenclature/items?
api_token=3e9a214215f493c4&page[size]=3&page[from_id]=10&page[direction]=reverseURI example
GET https://<account>.okdesk.com/api/v1/nomenclature/items?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 101,
"code": "item_code2",
"name": "Pay per time services",
"active": true,
"item_type": "service",
"unit": "man-hour",
"vendor_code": null,
"description": "",
"group": {
"id": 100,
"code": "group2",
"name": "Parent group"
}
},
{
"id": 100,
"code": "item_code1",
"name": "Delivery to the service center",
"active": true,
"item_type": "work",
"unit": "field trip",
"vendor_code": null,
"description": "",
"group": null
}
]Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"page": {
"size": [
"must be less than or equal to 100"
],
"direction": [
"must be one of: reverse, forward"
],
"from_id": [
"must be an integer"
]
}
}
}Creation of nomenclature item
POST/api/v1/nomenclature/items{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| code | string | required | Nomenclature item code |
| name | string | required | Nomenclature item name |
| item_type | string | required | Nomenclature type. Acceptable values: service, product, material, work |
| unit | string | required | Nomenclature item unit of measure |
| description | string | optional | Nomenclature item description |
| group_id | integer | optional | Group ID |
| vendor_code | string | optional | Item number |
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to action “Access to price-list management”.
URI example
POST https://<account>.okdesk.com/api/v1/nomenclature/items?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"nomenclature_item": {
"code": "item_code1",
"name": "Pay per time services",
"item_type": "service",
"unit": "man-hour",
"group_id": 99
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 100,
"code": "item_code1",
"name": "Pay per time services",
"active": true,
"item_type": "service",
"unit": "man-hour",
"vendor_code": null,
"description": null,
"group": {
"id": 99,
"code": "parent_group_code",
"name": "Parent group"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"nomenclature_item": {
"code": true,
"item_type": "incorrect"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"code": [
"must be a string"
],
"name": [
"is missing"
],
"item_type": [
"must be one of: service, product, material, work"
],
"unit": [
"is missing"
]
}
}Obtaining nomenclature item by id
GET/api/v1/nomenclature/items/{id}{?api_token}
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to action “Access to price-list management”.
URI example
GET https://<account>.okdesk.com/api/v1/nomenclature/items/100?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 100Nomenclature item ID.
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 100,
"code": "item_code1",
"name": "Pay per time services",
"active": true,
"item_type": "service",
"unit": "man-hour",
"vendor_code": null,
"description": null,
"group": {
"id": 99,
"code": "parent_group_code",
"name": "Parent group"
}
}Editing of nomenclature item
PATCH/api/v1/nomenclature/items/{id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Nomenclature item name |
| item_type | string | optional | Nomenclature type. Acceptable values: service, product, material, work |
| unit | string | optional | Nomenclature item unit of measure |
| description | string | optional | Nomenclature item description |
| group_id | integer | optional | Group ID |
| vendor_code | string | optional | Item number |
| active | boolean | optional | Activity status. Takes true or false value |
Restriction of access rights ¶
- This method is only available for keys associated with agents who have access to action “Access to price-list management”.
URI example
PATCH https://<account>.okdesk.com/api/v1/nomenclature/items/100?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 100Nomenclature item ID.
Request
with correct parametersHideShow
Headers
Content-Type: application/jsonBody
{
"nomenclature_item": {
"name": "Pay per time services",
"group_id": 99,
"active": false
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 100,
"code": "item_code1",
"name": "Pay per time services",
"active": false,
"item_type": "service",
"unit": "man-hour",
"vendor_code": null,
"description": null,
"group": {
"id": 99,
"code": "parent_group_code",
"name": "Parent group"
}
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"nomenclature_item": {
"active": "1"
}
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"active": [
"must be a boolean"
]
}
}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: 3e9a214215f493c4Authorization key.
- parent_code
string(optional) Example: serviceParent group code.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 8,
"name": "Service types",
"code": "service",
"type": "group",
"children": [
{
"id": 2,
"name": "Service",
"code": "service",
"default": true,
"available_for_client": true,
"inner": false,
"type": "type"
},
{
"id": 1,
"name": "Incident",
"code": "incident",
"default": false,
"available_for_client": false,
"inner": false,
"type": "type"
}
]
},
{
"id": 3,
"name": "Inner",
"code": "inner",
"default": false,
"available_for_client": false,
"inner": true,
"type": "type"
}
]Obtaining a list of ticket priorities
GET/api/v1/issues/priorities/{?api_token}
Please note ¶
For contact-associated keys only limited information will be available:
-
Item name;
-
Item code;
-
Item order position;
-
Information about the presence of the “by default” indicator in the ticket type;
-
Item color;
URI example
GET https://<account>.okdesk.com/api/v1/issues/priorities/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"name": "Low",
"code": "low",
"position": 1,
"default": true,
"color": "#8e9eb3",
"without_client": true,
"company_without_category": false,
"contact_without_company": false,
"available_for_client": true,
"company_category_codes": [
"client"
],
"company_ids": [
45
],
"employee_role_ids": [
1
]
},
{
"name": "Normal",
"code": "normal",
"position": 2,
"default": false,
"color": "#5cb85c",
"without_client": true,
"company_without_category": false,
"contact_without_company": false,
"available_for_client": true,
"company_category_codes": [],
"company_ids": [],
"employee_role_ids": []
},
{
"name": "High",
"code": "high",
"position": 3,
"default": false,
"color": "#ea2e49",
"without_client": true,
"company_without_category": false,
"contact_without_company": false,
"available_for_client": true,
"company_category_codes": [],
"company_ids": [],
"employee_role_ids": []
}
]Obtaining a list of ticket statuses
GET/api/v1/issues/statuses/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| final | boolean | optional | Final status indicator. Takes true or false value |
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: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"code": "opened",
"name": "Opened",
"color": "#ff8522",
"final": false,
"comment_required": false
},
{
"code": "delayed",
"name": "Delayed",
"color": "#ffc926",
"final": false,
"comment_required": false
},
{
"code": "completed",
"name": "Completed",
"color": "#5cb85c",
"final": true,
"comment_required": false
},
{
"code": "closed",
"name": "Сlosed",
"color": "#8e9eb3",
"final": true,
"comment_required": false
}
]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: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"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: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"code": "attr_string",
"name": "String",
"field_type": "ftstring",
"required": false,
"visible_on_time_entry_form": true,
"visible_on_time_entries_list": true
},
{
"code": "attr_date",
"name": "Date",
"field_type": "ftdate",
"required": false,
"visible_on_time_entry_form": true,
"visible_on_time_entries_list": true
},
{
"code": "attr_datetime",
"name": "Date/time",
"field_type": "ftdatetime",
"required": false,
"visible_on_time_entry_form": true,
"visible_on_time_entries_list": true
},
{
"code": "attr_checkbox",
"name": "Checkbox",
"field_type": "ftcheckbox",
"required": false,
"visible_on_time_entry_form": true,
"visible_on_time_entries_list": true
},
{
"code": "attr_select",
"name": "List item",
"field_type": "ftselect",
"required": false,
"visible_on_time_entry_form": true,
"visible_on_time_entries_list": true,
"field_type_values": [
"value_1",
"value_2"
]
},
{
"code": "attr_multiselect",
"name": "List item set",
"field_type": "ftmultiselect",
"required": false,
"visible_on_time_entry_form": true,
"visible_on_time_entries_list": true,
"field_type_values": [
"value_1",
"value_2"
]
},
{
"code": "attr_text",
"name": "Text",
"field_type": "fttext",
"required": false,
"visible_on_time_entry_form": true,
"visible_on_time_entries_list": true
}
]Scheme of additional attributes of equipment
GET/api/v1/equipments/parameters{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| equipment_kind_codes | array | optional | Array of equipment kind codes Example: equipment_kind_codes[]=EG |
Please note ¶
If array of equipment codes is passed, then additional attributes are returned that are available only for the passed equipment kind.
Restriction of access rights ¶
The method is available only for keys connected with agents. The agent requires the presence of his role in the “Available to the agents with the following roles” parameter.
URI example
GET https://<account>.okdesk.com/api/v1/equipments/parameters?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"code": "attr_string",
"name": "String",
"field_type": "ftstring",
"required": false,
"equipment_kind_codes": [
"laptop"
]
},
{
"code": "attr_date",
"name": "Date",
"field_type": "ftdate",
"required": false,
"equipment_kind_codes": [
"laptop"
]
},
{
"code": "attr_datetime",
"name": "Date/time",
"field_type": "ftdatetime",
"required": false,
"equipment_kind_codes": [
"laptop"
]
},
{
"code": "attr_checkbox",
"name": "Checkbox",
"field_type": "ftcheckbox",
"required": false,
"equipment_kind_codes": [
"laptop"
]
},
{
"code": "attr_select",
"name": "List item",
"field_type": "ftselect",
"required": false,
"equipment_kind_codes": [
"laptop"
],
"field_type_values": [
"value_1",
"value_2"
]
},
{
"code": "attr_multiselect",
"name": "List item set",
"field_type": "ftmultiselect",
"required": false,
"equipment_kind_codes": [
"laptop"
],
"field_type_values": [
"value_1",
"value_2"
]
},
{
"code": "attr_text",
"name": "Text",
"field_type": "fttext",
"required": false,
}
]Scheme of additional attributes of agreement
GET/api/v1/agreements/parameters{?api_token}
Restriction of access rights ¶
The method is available only for keys connected with agents. Only the set of additional attributes is returned for which one of the employee roles is specified in the “Available for display to employees with a role” parameter.
URI example
GET https://<account>.okdesk.com/api/v1/agreements/parameters?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"code": "attr_string",
"name": "String",
"field_type": "ftstring",
"required": false,
"visible_on_agreement_form": true,
"visible_on_agreement_list": true,
"visible_on_issues_list": true
},
{
"code": "attr_date",
"name": "Date",
"field_type": "ftdate",
"required": false,
"visible_on_agreement_form": true,
"visible_on_agreement_list": true,
"visible_on_issues_list": true
},
{
"code": "attr_datetime",
"name": "Date/time",
"field_type": "ftdatetime",
"required": false,
"visible_on_agreement_form": true,
"visible_on_agreement_list": true,
"visible_on_issues_list": true
},
{
"code": "attr_checkbox",
"name": "Checkbox",
"field_type": "ftcheckbox",
"required": false,
"visible_on_agreement_form": true,
"visible_on_agreement_list": true,
"visible_on_issues_list": true
},
{
"code": "attr_select",
"name": "List item",
"field_type": "ftselect",
"required": false,
"visible_on_agreement_form": true,
"visible_on_agreement_list": true,
"visible_on_issues_list": true,
"field_type_values": [
"value_1",
"value_2"
]
},
{
"code": "attr_multiselect",
"name": "List item set",
"field_type": "ftmultiselect",
"required": false,
"visible_on_agreement_form": true,
"visible_on_agreement_list": true,
"visible_on_issues_list": true,
"field_type_values": [
"value_1",
"value_2"
]
},
{
"code": "attr_text",
"name": "Text",
"field_type": "fttext",
"required": false,
"visible_on_agreement_form": true,
"visible_on_agreement_list": true,
"visible_on_issues_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 ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
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=specialURI example
GET https://<account>.okdesk.com/api/v1/equipments/kinds/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"id": 5,
"code": "005",
"name": "somewhatspecialequipment",
"description": "somewhat special equipment",
"visible": true,
"equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
"parameters": [
{
"name": "Some_parameter 3",
"field_type": "ftcheckbox"
}
]
},
{
"id": 8,
"code": "008",
"name": "specialequipment",
"description": "special equipment",
"visible": true,
"equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
"parameters": [
{
"name": "Some_parameter 2",
"field_type": "ftcheckbox"
}
]
},
{
"id": 10,
"code": "010",
"name": "veryspecialequipment",
"description": "very special equipment",
"visible": true,
"equipment_name_format": "{{{TYPE}}} {{{VENDOR}}} {{{MODEL}}} {{{SN}}} {{{INV}}}",
"parameters": [
{
"name": "Some_parameter 1",
"field_type": "ftcheckbox"
},
{
"name": "Some_parameter 2",
"field_type": "ftcheckbox"
}
]
}
]Creating equipment type
POST/api/v1/equipments/kinds/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | required | Equipment type name |
| code | string | required | Equipment type code |
| description | string | optional | Equipment type description |
| parameter_codes | array of string | optional | Array of codes of linked extended attributes of equipment |
| equipment_name_format | string | optional | Equipment name template |
Restriction of access rights ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/kinds/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_kind": {
"code": "sample_code",
"name": "sample_name",
"description": "sample_text",
"equipment_name_format": "{{{SN}}} {{{INV}}}",
"parameter_codes": [
"001",
"002"
]
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "sample_code",
"name": "sample_name",
"description": "sample_text",
"visible": true,
"equipment_name_format": "{{{SN}}} {{{INV}}}",
"parameters": [
{
"name": "Parameter 1",
"field_type": "ftstring"
},
{
"name": "Parameter 2",
"field_type": "ftstring"
}
]
}Editing of equipment type
PATCH/api/v1/equipments/kinds/{kind_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Equipment type name |
| description | string | optional | Equipment type description |
| parameter_codes | array of string | optional | Array of codes of linked extended attributes of equipment |
| visible | boolean | optional | Nesting indicator |
| equipment_name_format | string | optional | Equipment name template |
Restriction of access rights ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
URI example
PATCH https://<account>.okdesk.com/api/v1/equipments/kinds/57?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- kind_id
integer(required) Example: 57Edited equipment type ID
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_kind": {
"name": "changed_name",
"description": "changed_text",
"visible": false,
"equipment_name_format": "{{{SN}}} {{{INV}}}",
"parameter_codes": [
"001",
"003"
]
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "code",
"name": "changed_name",
"description": "changed_text",
"visible": false,
"equipment_name_format": "{{{SN}}} {{{INV}}}",
"parameters": [
{
"name": "Parameter 1",
"field_type": "ftstring"
},
{
"name": "Parameter 3",
"field_type": "ftcheckbox"
}
]
}Obtaining equipment manufacturers list
GET/api/v1/equipments/manufacturers/{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| search_string | string | optional | Target substring in equipment manufacturer name or code |
| page | associative array | optional | Associative array of parameters for a per-page display of the equipment manufacturer list (detailed description is available in the table below). |
Valid per-page display parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| size | integer | optional | Number of returned entries. Cannot exceed 100. Example: page[size]=30 |
| from_id | integer | optional | The ID of the equipment manufacturer starting the fetch. By default (if not set by direction), the fetch is performed starting from the from_id in the equipment manufacturer id decreasing order. Example: page[from_id]=10 |
| direction | string | optional | Fetch direction. There are two values available: reverse and forward. reverse returns records with ID lower than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment manufacturer’s largest id. forward returns records with ID higher than from_id value, if the parameter from_id is transferred. If there is no from_id parameter, fetch is performed based on the equipment manufacturer’s lowest id. Example: page[direction]=forward |
Restriction of access rights ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
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=specialURI example
GET https://<account>.okdesk.com/api/v1/equipments/manufacturers/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"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 ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/manufacturers/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_manufacturer": {
"code": "sample_code",
"name": "sample_name",
"description": "sample_text"
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "sample_code",
"name": "sample_name",
"description": "sample_text",
"visible": true
}Editing equipment manufacturer
PATCH/api/v1/equipments/manufacturers/{manufacturer_id}{?api_token}
Valid query parameters: ¶
| Name | Type | Mandatory | Description |
|---|---|---|---|
| name | string | optional | Equipment manufacturer name |
| description | string | optional | Equipment manufacturer description |
| visible | boolean | optional | Nesting indicator |
| equipment_name_format | string | optional | Equipment name template |
Restriction of access rights ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
URI example
PATCH https://<account>.okdesk.com/api/v1/equipments/manufacturers/57?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- manufacturer_id
integer(required) Example: 57ID of editing equipment manufacturer
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_manufacturer": {
"name": "changed_name",
"description": "changed_text",
"visible": false
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"id": 57,
"code": "code",
"name": "changed_name",
"description": "changed_text",
"visible": false
}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 ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
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=specialURI example
GET https://<account>.okdesk.com/api/v1/equipments/models/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"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 ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
URI example
POST https://<account>.okdesk.com/api/v1/equipments/models/?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_model": {
"code": "model_code",
"name": "model_name",
"description": "sample",
"equipment_kind_id": 1,
"equipment_manufacturer_id": 1
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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 ¶
This method is only available for keys associated with agents who have access to action “Access to viewing and editing directories of equipment types, manufacturers, and models”.
URI example
PATCH https://<account>.okdesk.com/api/v1/equipments/models/57?api_token=3e9a214215f493c4
URI parameters
HideShow
- api_token
string(required) Example: 3e9a214215f493c4Authorization key.
- model_id
integer(required) Example: 57ID of editing equipment model
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"equipment_model": {
"name": "changed_name",
"description": "changed_text",
"visible": false,
"equipment_kind_id": 2,
"equipment_manufacturer_id": 3
}
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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: 3e9a214215f493c4Authorization key.
Response
200HideShow
Headers
Content-Type: application/jsonBody
[
{
"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: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"user_login": "employee@okdesk.com",
"expire_after": 60,
"one_time": false
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"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": [
{
"code": "code2",
"name": "Date",
"field_type": "ftdate",
"value": "2024-01-25"
}
]
}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: 3e9a214215f493c4Authorization key.
Request
HideShow
Headers
Content-Type: application/jsonBody
{
"user_type": "employee",
"id": 1
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"api_key": "12345ghy8be7c71623cad7590b8a5q3"
}Request
HideShow
Headers
Content-Type: application/jsonBody
{
"user_type": "employee",
"id": 12
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": "The requested user has been disabled"
}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: 3e9a214215f493c4Authorization key.
- id
integer(required) Example: 2User internal ID
- user_type
string(required) Example: employeeUser type
Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"api_key": "430379fd78be7c71623cad7590b8a23d"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": "The requested user has been disabled"
}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 parametersHideShow
Headers
Content-Type: application/jsonBody
{
"login": "user",
"password": "Password"
}Response
200HideShow
Headers
Content-Type: application/jsonBody
{
"api_key": "430379fd78be7c71623cad7590b8a23d"
}Request
with incorrect parametersHideShow
Headers
Content-Type: application/jsonBody
{
"login": "user"
}Response
422HideShow
Headers
Content-Type: application/jsonBody
{
"errors": {
"password": [
"is missing"
]
}
}
Adding a comment
POST
/api/v1/issues/{issue_id}/comments{?api_token}Valid query parameters: ¶
Acceptable types: employee (default) - agent, contact - contact person
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: ¶
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
string(required) Example: 3e9a214215f493c4Authorization key.
integer(required) Example: 254ticket ID.
Headers
Content-Type: application/jsonBody
{ "comment": { "content": "Very soon an engineer will come to you to solve the problem.", "public": true, "author_id": 10, "author_type": "employee" } }200Headers
Content-Type: application/jsonBody
{ "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" } }with attached filesHeaders
Content-Type: multipart/form-dataBody
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"200Headers
Content-Type: application/jsonBody
{ "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" } }with incorrect parametersHeaders
Content-Type: application/jsonBody
{ "comment": { "content": "Very soon an engineer will come to you to solve the problem.", "public": false, "author_id": 22221, "author_type": "contact" } }422Headers
Content-Type: application/jsonBody
{ "errors": { "author_presence": [ "user is not found" ], "contact_comment_cannot_be_private": [ "the contact cannot be an author of a private comment" ] } }